@mapier/imsg-sdk 0.5.0 → 0.7.0

package/docs/gateway-contract.md

@@ -53,6 +53,7 @@ claim about send, reaction, or group mutation behavior.
 interface Gateway {
   readonly capabilities: {
     emojiTapback: boolean;
+    tapbackPart: boolean;
     stickerSend: boolean;
     groupPhoto: boolean;
     groupParticipants: boolean;
@@ -63,6 +64,9 @@ interface Gateway {
     mentionFormatting: boolean;
     sharedLocations: boolean;
     locationRequest: boolean;
+    extensionCardSend: boolean;
+    extensionCardUpdate: boolean;
+    multipartSend: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -78,8 +82,20 @@ interface Gateway {
   checkHandle(address: string, opts?: { aliasType?: 'phone' | 'email' }): Promise<HandleCheck>;
 
   // Tier 2 (bridge-backed — imsg launch required). See "Tier 2" below.
-  tapback(chatId: number, targetGuid: string, reaction: Reaction, remove?: boolean): Promise<ReactResult>;
-  emojiTapback(chatId: number, targetGuid: string, emoji: string, remove?: boolean): Promise<ReactResult>;
+  tapback(
+    chatId: number,
+    targetGuid: string,
+    reaction: Reaction,
+    remove?: boolean,
+    partIndex?: number,
+  ): Promise<ReactResult>;
+  emojiTapback(
+    chatId: number,
+    targetGuid: string,
+    emoji: string,
+    remove?: boolean,
+    partIndex?: number,
+  ): Promise<ReactResult>;
   sendRich(
     chatId: number,
     text: string,
@@ -97,13 +113,23 @@ interface Gateway {
   ): Promise<SendResult>;
   sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
   sendRichLink(chatId: number, url: string): Promise<SendResult>;
+  sendExtensionCard(
+    chatId: number,
+    card: ExtensionCard,
+    opts?: { update?: ExtensionCardHandle },
+  ): Promise<ExtensionCardResult>;
+  sendMultipart(
+    chatId: number,
+    parts: readonly MultipartPart[],
+    opts?: { replyToGuid?: string; effect?: string; subject?: string },
+  ): Promise<MultipartResult>;
   editMessage(chatId: number, targetGuid: string, text: string): Promise<{
     ok: boolean;
     skipped?: 'unchanged';
     effectStarted?: boolean;
   }>;
-  unsendMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
-  deleteMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
+  unsendMessage(chatId: number, targetGuid: string): Promise<MessageRemovalResult>;
+  deleteMessage(chatId: number, targetGuid: string): Promise<MessageRemovalResult>;
   setTyping(chatId: number, on: boolean): Promise<{ ok: boolean }>;
   markRead(chatId: number): Promise<{ ok: boolean }>;
   renameGroup(chatId: number, name: string): Promise<GroupMutationResult>;
@@ -201,7 +227,66 @@ interface GroupMutationResult {
     | 'refused'             // proven rejection before IMChat — effectStarted:false
     | 'fire-failed'         // the call errored, may have applied — effectStarted:true
     | 'unverified'          // fired, never confirmed in the window — effectStarted:true
-    | 'verify-read-failed'; // fired, the verification read broke  — effectStarted:true
+    | 'verify-read-failed'  // fired, the verification read broke  — effectStarted:true
+    | 'preflight-read-failed'; // a PREflight read broke, nothing fired — effectStarted:false
+}
+
+// unsendMessage / deleteMessage (M2B-43). Same shape, same shared reason
+// table: a success is bare, a failure always names where certainty was lost.
+interface MessageRemovalResult {
+  ok: boolean;
+  effectStarted?: boolean;
+  reason?: GroupMutationFailure;
+}
+
+// sendExtensionCard (M2B-46). A card belonging to a third-party iMessage app
+// extension; the balloon identifier is composed from teamId + extensionBundleId
+// on the native side and never accepted whole.
+interface ExtensionCard {
+  teamId: string;              // exactly 10 characters of A-Z0-9
+  extensionBundleId: string;   // the MESSAGES EXTENSION's id, reverse-DNS, no ':'
+  appName: string;
+  appStoreId?: number;         // positive integer; without it an unmatched card leads nowhere
+  caption: string;
+  subcaption?: string;
+  summaryText?: string;        // the line left behind once an update replaces this card
+  url: string;                 // the app's own state; any scheme, real cards use data:
+  liveLayout?: boolean;        // default true — see the verb entry for what each value shows
+}
+
+// The ONLY update target this SDK accepts, and the reason it is a pair rather
+// than a guid: every update must name the session's FIRST card.
+interface ExtensionCardHandle {
+  sessionId: string;
+  firstCardMessageGuid: string;
+}
+
+interface ExtensionCardResult {
+  ok: boolean;
+  sessionId?: string;
+  messageGuid?: string;          // THIS row (the card, or the update row) — not the update target
+  handle?: ExtensionCardHandle;  // what a later update passes back as opts.update; present exactly when `updatable`
+  updatable?: boolean;           // always present on ok:true
+  balloonBundleId?: string;
+  liveLayout?: boolean;
+  effectStarted?: boolean;
+  reason?: GroupMutationFailure; // only unsupported / refused / fire-failed are reachable
+}
+
+// sendMultipart (M2B-55). One message made of several parts, in the order
+// given — that order is each part's NUMBER, the same number tapback's
+// `partIndex` names. Audio is not a part: the voice flag is message-wide, so a
+// voice note still goes alone through sendAttachment.
+type MultipartPart =
+  | { kind: 'text'; text: string; textFormatting?: TextFormatRange[] }  // the same ranges sendRich takes
+  | { kind: 'file'; filePath: string };                                 // a path on the HOST Mac
+
+interface MultipartResult {
+  ok: boolean;
+  guid?: string;                 // absent when Messages had not exposed the row yet; never synthesized
+  partCount?: number;            // the host's own count of the parts it built
+  effectStarted?: boolean;
+  reason?: GroupMutationFailure; // only unsupported / refused / fire-failed are reachable
 }
 ```
 
@@ -238,6 +323,15 @@ confirmed-mention attribute key resolves at runtime (imsg#13); emoji
 additionally requires the selected RPC binary
 to report `rpc_features:["tapback.emoji"]`. That second half prevents a
 patched dylib behind a stock CLI from false-advertising custom emoji support.
+Part-level tapbacks require `tapbackPart`, which the helper computes from the
+part's own chat item plus an associated-message initializer taking a range —
+and which no other tapback marker may stand in for, because a helper without it
+does not reject `part_index`, it writes a corrupt row (M2B-45, above).
+Multipart sends require `multipartSend`, composed by the helper from the
+file-transfer centre plus the attachment IMMessage initializer, and equally
+un-substitutable: a helper predating file parts reads only each part's `text`,
+so it DROPS every file part without a word and answers ok with a short
+`parts_count` (M2B-55, below).
 Missing status, malformed JSON, or absent markers fail closed.
 `FakeGateway.capabilities` mirrors this gate and can disable the same surface
 for parity tests. A remote adapter (e.g. imsg-agent's connector) must gate on
@@ -250,11 +344,17 @@ guid by scanning `history(chatId, 30)` — the same 30-message ceiling
 `recentReactions` already documents above — so a guid older than that is as
 invisible to these methods as it is to `recentReactions`. `tapback` and
 `deleteMessage` pre-check against that scan before firing, so they return
-`{ ok: false }` without touching anything, and so does `editMessage` (it also
-refuses a message that is not `is_from_me`); `unsendMessage` fires the RPC
+`ok: false` without touching anything (`tapback`/`emojiTapback`/`deleteMessage`
+say so explicitly: `effectStarted:false, reason:'refused'`), and so does
+`editMessage`
+(it also refuses a message that is not `is_from_me`); `unsendMessage` fires the RPC
 first and only finds the ceiling on the VERIFY pass, so a guid outside the
-window still reports `{ ok: false }` but may have mutated the real row on the
-way there — "no confirmable effect," not a guaranteed no-op. FakeGateway
+window reports `ok: false, effectStarted: true, reason: 'unverified'` and may
+have mutated the real row on the way there — "no confirmable effect," not a
+guaranteed no-op. Until M2B-43 that case returned `{ ok: true }`: the verify
+predicate read an ABSENT row as a cleared one, so an out-of-window (or
+merely lagging) guid reported a retraction nobody had observed. Unsend leaves
+a tombstone row, so absence is missing evidence, never success. FakeGateway
 must enforce the identical window regardless: finding the target guid by
 scanning ALL of `this.messages` unconditionally would let the fake succeed
 at targeting a message the real path can't reach (parity rule 2) — a
@@ -262,7 +362,7 @@ guid-targeted verb "working" in the fake against a message 40 rows back but
 refusing on the real path is exactly the trap this contract exists to
 prevent.
 
-- **`tapback(chatId, targetGuid, reaction, remove?)`** — a second, bridge-based
+- **`tapback(chatId, targetGuid, reaction, remove?, partIndex?)`** — a second, bridge-based
   tapback path alongside `react()`. What it adds: targets **any** message guid
   in the chat, not just the newest incoming bubble; works in **group** chats
   (the bridge has no focused-window check to defeat, unlike the AppleScript
@@ -276,13 +376,88 @@ prevent.
   deliberate: "fix: reject unsupported custom emoji reaction sends instead of
   taking a no-op AppleScript path" (#55). So `reaction` stays the closed
   `Reaction` type here too.
-- **`emojiTapback(chatId, targetGuid, emoji, remove?)`** — Mapier-fork extension
+- **`emojiTapback(chatId, targetGuid, emoji, remove?, partIndex?)`** — Mapier-fork extension
   backed by `IMEmojiTapback` + `IMTapbackSender`. It targets any guid in the
   same 30-message scan window as `tapback`, uses explicit add/remove guards,
   and verifies history for `type:"custom"` plus the exact emoji before
   returning success. The RPC sends `emoji` instead of `kind`; sending both
   would fall back into stock imsg's classic-6 normalizer. Live-verified on the
   host Mac with 👻 and 💀; chat.db records `associated_message_type=2006`.
+
+  **A tapback failure says which failure it is** (M2B-40). `tapback` and
+  `emojiTapback` are the only reaction path a consumer has left once
+  `reaction.apply` lost its minters (M2B-37), and they used to answer a bare
+  `ok:false` from four different positions. On `ok:false` they now carry the
+  same `reason` / `effectStarted` pair the group verbs do (`GroupMutationFailure`,
+  one shared table, so a reason cannot mean two things):
+
+  - **`unsupported`** (`effectStarted:false`) — `emojiTapback` without the
+    `emojiTapback` capability marker.
+  - **`refused`** (`effectStarted:false`) — the guid is not in the 30-message
+    scan window, the emoji is empty, or the helper rejected the call before its
+    send: a `-32602`, or a `-32603` whose `error.data` carries one of
+    `TAPBACK_PROVEN_REJECTIONS` (`gateway/tapback.ts`, read off
+    `handleSendReaction`'s returns above `[sender send]` / `[chat sendMessage:]`).
+  - **`fire-failed`** (`effectStarted:true`) — the call errored without proving
+    the helper stopped short. That deliberately includes `send-reaction failed:
+    …`: it wraps an NSException caught around the whole build-and-send block, so
+    the text cannot say which side of the send raised it.
+  - **`unverified`** (`effectStarted:true`) — fired cleanly, and six 1 s history
+    reads never showed the wanted state.
+  - **`verify-read-failed`** (`effectStarted:true`) — fired cleanly, then a
+    verification read threw. This used to escape as an exception.
+
+  `react()` is unchanged and still answers a bare `ok:false`; an absent
+  `effectStarted` must keep being treated as ambiguous.
+
+  **A tapback lands on ONE part of a message** (M2B-45). A message carrying two
+  photos has parts 0 and 1, so `partIndex: 1` reacts to the second photo alone.
+  Omitted or `0` is what both verbs always did, and the RPC for it is
+  unchanged — `part_index` is not sent at all, so a host that has never heard
+  of parts sees the same request it always did. Both verbs, add and remove,
+  classic and emoji, behave identically here.
+
+  - **Capability-gated on `tapbackPart`, and a part >= 1 without it is
+    `unsupported` (`effectStarted:false`), never a quiet part 0.** This marker
+    guards a SILENT corruption rather than a rejection, which is why nothing
+    else may stand in for it: an older helper *accepts* `part_index` and writes
+    a row whose `p:N/<guid>` prefix disagrees with its range, so the recipient's
+    phone draws the reaction on **every** photo while Messages discards the
+    sender's own row — unverifiable and unremovable. Production Macs run such a
+    helper. Downgrading to part 0 instead would react to the wrong photo and
+    report success, so the SDK refuses before building the RPC.
+  - **`partIndex` must be a non-negative integer**, checked client-side
+    (`tapbackPartRefusal`, `gateway/tapback.ts`): `1.5`, `-1` and `NaN` are
+    `refused` with nothing sent, matching the native's `invalid params`. A part
+    that cannot be read is never taken as 0.
+  - **A part the message does not have is refused before anything is sent** —
+    the helper counts the parts and returns `Message <guid> has no part <n>`,
+    which `TAPBACK_PROVEN_REJECTIONS` matches as `refused`
+    (`effectStarted:false`). FakeGateway enforces the same rule from its own
+    part count: the number of attachments, minimum 1. That model is
+    deliberately conservative — a text-plus-photos message really has more
+    parts than the fake counts, so the fake refuses parts the host would accept
+    and never the reverse (parity rule 2).
+  - **The guards and the verify compare the PART, not just the reaction.** One
+    sender can hold the same reaction type on part 0 and part 1 as two separate
+    reactions; they used to collapse into one. So reacting to photo 2 while
+    photo 1 already carries that reaction fires normally instead of answering
+    `already-reacted`, a remove on part 1 leaves part 0's alone, and the
+    verify-after-fire pass looks for the reaction on the part that was asked
+    for.
+  - **`react()` is deliberately left part-BLIND.** It drives AppleScript, which
+    has no part-level form, and its tapback is a toggle whose guard exists to
+    stop a second react from switching the first one off. Whether that toggle
+    would reach a reaction sitting on part 1 is Messages.app behaviour nobody
+    has verified on a host, so its guard keeps matching any part exactly as it
+    always did and declines instead. Only the bridge verbs compare parts.
+  - **Reading back:** a reaction that named a part carries `target_part` on the
+    `reactions[]` aggregate and `reaction_target_part` on a reaction event row;
+    `recentReactions` surfaces it as `ReactionNote.targetPart`. All three are
+    **absent** when the reaction named the whole message, so every comparison
+    goes through `reactionPart()` / `reactionOnPart()` (exported), which read
+    absent as 0. `reacted_to_guid` stays the bare message guid — the part never
+    appears in it.
 - **`sendRich(chatId, text, opts?)`** — real and confirmed present on the
   host's selected patched imsg 0.13.x (`send.rich`, `RPCServer+BridgeMessageHandlers.swift`
   `handleSendRich`; shipped well before 0.12.3 per CHANGELOG). Targets an
@@ -380,6 +555,131 @@ prevent.
   guid** (unlike text/poll/attachment, which return a guid) — the URL-preview
   balloon lands as its own row later. `SendResult.guid` is therefore always
   undefined here; FakeGateway must not return one either.
+- **`sendExtensionCard(chatId, card, opts?)`** — `extension_card.send`
+  (`RPCServer+ExtensionCardHandler.swift`, `handleSendExtensionCard`), the kind
+  of balloon a third-party iMessage app extension sends. Targets an
+  **existing** chat only. The balloon identifier is composed on the native side
+  from `teamId` + `extensionBundleId` and is never accepted whole, so a caller
+  cannot claim an arbitrary app's balloon. Two capability markers gate it, read
+  from `imsg status --json` like every other patched verb: `extensionCardSend`
+  (the payload initializer polls also use) and `extensionCardUpdate` (that plus
+  the associated-message initializer). **Neither implies the other** — a host
+  can send cards and be unable to replace one — so a `sendExtensionCard` with
+  an `update` needs both and is `unsupported` without the second.
+
+  **What the recipient sees** (all three observed on a real phone, 2026-09-20):
+  with `liveLayout` true (the default) and the app installed, the installed
+  extension draws the card itself and the `caption` is never seen; with
+  `liveLayout:false` and the app installed, the app's icon beside *this card's*
+  caption and subcaption — the mode to use when the text is the point; without
+  the app, a small static card that links to the App Store page only when
+  `appStoreId` is given. **Cards never carry a picture.**
+
+  **The first-card rule, which is what shapes this API.** An update must always
+  name the session's **FIRST** card — the same `updates_message_guid` for every
+  update in the session, including the fifth, plus that session's id. It is not
+  a chain. Aiming an update at a *previous update's* guid does not replace
+  anything: that card arrives as a separate new card and stays in the thread as
+  an orphan, and it looks exactly like success (`ok:true`, a real guid,
+  delivered). **Nothing on the Mac can catch this**, because it cannot know
+  which guid began a session. So this verb does not take a guid at all: a first
+  send returns an `ExtensionCardHandle` as `result.handle` (`{sessionId,
+  firstCardMessageGuid}`); every update passes it back **unchanged** as
+  `opts.update` and gets the *same* handle out, never one built from its own
+  row. A caller doing `handle = result.handle` after each update therefore
+  stays correct by construction. A
+  handle assembled by hand out of an update's `messageGuid` is still wrong and
+  still cannot be detected — by the SDK or by the host — which is why
+  `ExtensionCardHandle` is documented as opaque.
+
+  **`updatable` answers the only question on a success.** `guid` is omitted by
+  the native handler when Messages has not exposed the row's guid yet, and
+  `ok:true` either way. Rather than invent one, `updatable:false` (with no
+  `update`) says plainly that this card can never be updated — send a fresh one
+  instead. On `ok:true`, `messageGuid` is *this* row: the card on a first send,
+  the associated update row on an update.
+
+  **Validation happens before the RPC**, mirroring
+  `ExtensionCardRequest.swift`: team id shape, reverse-DNS extension bundle id
+  without `':'`, required `appName`/`caption`/`url`, positive integer
+  `appStoreId`, strict boolean `liveLayout`, a 4096 **UTF-16 unit** cap on
+  every string, and both halves of an update handle present and UUID-shaped.
+  One deliberate divergence: `url` must be **absolute** here, while the helper
+  accepts anything `URL(string:)` parses — a card's URL is the extension's own
+  state (`data:` or `https:` in practice), never a relative path. Every one of
+  these is a proven no-op (`effectStarted:false`, `reason:'refused'`).
+
+  **No verification pass exists.** `imsg history` selects `payload_data` as
+  NULL for bundle ids it does not decode, so a card reads back with an empty
+  payload and there is nothing to confirm against; this verb therefore never
+  mints `unverified`, `verify-read-failed` or `preflight-read-failed`, and only
+  `unsupported` / `refused` / `fire-failed` are reachable. A caller that needs
+  delivery proof reads `sendStatus(messageGuid)`. `EXTENSION_CARD_PROVEN_REJECTIONS`
+  (`gateway/extension-card.ts`) are `handleSendExtensionCard`'s and the card
+  builder's returns above the IMChat call; `send-extension-card failed:` is
+  deliberately **not** among them, because that `@try` wraps the whole
+  build-and-send block. FakeGateway reaches only the proven half.
+- **`sendMultipart(chatId, parts, opts?)`** — `send.multipart`
+  (`RPCServer+MultipartHandler.swift` → `handleSendMultipart` in
+  `IMsgInjected.m`). Several parts as **one message**, targeting an **existing**
+  chat only. Gated on `multipartSend`, and the gate covers the whole verb
+  including a text-only list: the marker guards a silent LOSS rather than a
+  rejection (a helper predating file parts drops them and answers ok), so a
+  caller must never be left to discover mid-list that this host eats photos.
+
+  **What "one message" means on a phone** — proven on a real iPhone from the
+  lab Mac (macOS 26.6.2) on 2026-09-21, through the native CLI:
+  one notification and one `chat.db` row, **not** one bubble. Each part draws as
+  its own bubble, in the order given, and consecutive photos are gathered by the
+  receiving phone into a stack (five photos arrived as one stack labelled
+  "5 photos"). Two text parts in a row are fine — two bubbles — so, unlike
+  Linq, this verb allows them. A text part with a **trailing newline draws an
+  empty last line** in its bubble, so callers must not add one (the
+  single-attachment path's caption does, which is a native wart, not a model to
+  copy). **Part number = index in `parts`**, and that is exactly the
+  `partIndex` a later `tapback` names. Audio is not a part: the voice flag is
+  message-wide, so a voice note still goes alone through `sendAttachment`.
+
+  **`effect`, `subject` and `replyToGuid` are message-wide**, read by the
+  native handler exactly as `send.rich` reads them — IMCore has one of each per
+  message, never one per part. Per-part `textFormatting` is the `sendRich`
+  range vocabulary scoped to that part, offsets counted in that part's own
+  text; a mention still needs `mentionFormatting` and is `unsupported` without
+  it. Formatting on a **file** part is refused rather than dropped.
+
+  **Validation happens before the RPC**, mirroring the native pass that runs
+  before a single transfer is staged: a non-empty array, every entry an object
+  of a known `kind`, non-empty `text`, non-empty `filePath` carrying no newline
+  or NUL, per-part formatting through the same `textFormattingRefusal` sendRich
+  uses, and the Mac-side caps **100 parts / 40 file parts**
+  — plus one rule that exists only because of how this verb fails: a part
+  carrying **both** a `text` and a `filePath` is refused *before* its `kind` is
+  consulted, never resolved by the label. Whichever branch the label chose would
+  drop the other key without a word, and losing part content in silence is the
+  failure the whole verb exists to remove; it must not come back in through a
+  caller that names a part wrong. The native handler refuses it by index for the
+  same reason (an empty string counts as absent on both keys, on both sides)
+  (`MULTIPART_MAX_PARTS` / `MULTIPART_MAX_FILE_PARTS`, mirroring
+  `MultipartLimits` and `kMaxMultipartParts`). Each is a proven no-op
+  (`effectStarted:false`, `reason:'refused'`). Two native checks are
+  deliberately **not** mirrored: the 100 MiB total-byte cap and whether each
+  file exists. This SDK never touches the filesystem — the path belongs to the
+  Mac — so a local check would make the fake and the real path disagree in both
+  directions; a missing file is the helper's refusal, classified through
+  `MULTIPART_PROVEN_REJECTIONS`.
+
+  **No verification pass exists**, for the reason `sendAttachment` has none:
+  the synchronous response carries the message's guid, which is the proof to
+  read `sendStatus()` on, while the row Messages writes at dispatch says
+  nothing about the upload that follows (`is_sent` stays 0 until the bytes are
+  out). So only `unsupported` / `refused` / `fire-failed` are reachable.
+  `send-multipart failed:` is deliberately **not** a proven rejection: that
+  `@try` wraps the whole build-and-dispatch block. `partCount` is the **host's**
+  count of the parts it built and is never replaced with the caller's list
+  length — a count shorter than the list is precisely how a helper that dropped
+  file parts would show up. There is deliberately no numeric `id`: the native
+  result sets `message_id` to the message GUID, so no rowid exists on the real
+  path and FakeGateway must not hand back one either.
 - **`editMessage(chatId, targetGuid, text)`** — `message.edit`
   (`handleMessageEdit`; imsg `docs/edit.md`). Capability-gated on the
   `editMessage` marker (see above): on macOS 27 the helper calls the
@@ -432,6 +732,48 @@ prevent.
   and was absent in another). imsg exposes no `is_unsent`/`is_deleted` marker,
   so after a guid pre-check, delete `{ok:true}` means only that the RPC
   dispatched. The fake conservatively leaves its history row unchanged.
+
+  **A failure says which failure it is** (`MessageRemovalResult`, M2B-43).
+  Both verbs used to answer a bare `ok:false` whether nothing had fired or a
+  retraction had gone out unconfirmed, so a consumer had to settle every
+  failure as possibly-applied — the un-retirable rows of M2B-14. They now
+  carry the same `reason`/`effectStarted` pair through the same shared table
+  as the group verbs and tapback. The native layer contributes nothing here:
+  `message.unsend` and `message.delete` discard the bridge payload and answer
+  a hardcoded `{"ok": true}` on invocation, and neither verb verifies
+  anything, so every distinction below is either a helper refusal string or
+  one of the SDK's own read-backs.
+
+  - **`refused`** (`effectStarted:false`) — nothing fired. For `deleteMessage`,
+    the guid was not in the 30-message scan window after the pre-check poll.
+    For either verb, a `-32602`, or a `-32603` whose `error.data` carries one
+    of `UNSEND_PROVEN_REJECTIONS` / `DELETE_PROVEN_REJECTIONS`
+    (`gateway/message-removal.ts`, read off `handleUnsendMessage` /
+    `handleDeleteMessage`'s returns above the IMChat call). Note
+    `deleteChatItems:` is checked per call and advertises no `imsg status`
+    marker, so an unsupported host arrives as this refusal rather than as an
+    `unsupported` capability gate.
+  - **`preflight-read-failed`** (`effectStarted:false`) — `deleteMessage`'s
+    pre-check read threw, so the target was never looked for and nothing
+    fired. Kept apart from `refused` because it names the host's history read
+    as broken, not the caller's target. This used to escape as an exception.
+  - **`fire-failed`** (`effectStarted:true`) — the call errored without
+    proving the helper stopped short. Deliberately includes `unsend-message
+    failed` / `delete-message failed` and any bare NSException reason: the
+    helper's `@try` wraps only the selector invocation, so the text cannot say
+    which side of it raised. A bridge timeout lands here too.
+  - **`unverified`** (`effectStarted:true`) — `unsendMessage` only. It fired
+    cleanly and six 1 s history reads never showed the row with its text
+    cleared, including the out-of-window case (see the guid-targeting window
+    above, which this change also corrected).
+  - **`verify-read-failed`** (`effectStarted:true`) — `unsendMessage` only.
+    Fired cleanly, then a verification read threw. This used to escape as an
+    exception.
+
+  `deleteMessage` never mints `unverified`/`verify-read-failed`: it has no
+  postcondition to read, so once its RPC returns there is nothing left to
+  confirm. FakeGateway reaches only the proven half (`refused`) — it has no
+  bridge to time out on and no host read to lose.
 - **`setTyping(chatId, on)`/`markRead(chatId)`** — `typing`/`read`
   (`handleTyping`/`handleRead`). **Fire-and-forget: no observable effect
   through anything this Gateway exposes.** `is_read`/`date_read` are real
@@ -849,6 +1191,59 @@ the phone, created that day) and group chat 12 (three phone handles):
   backgrounds) THEN failure`). That is per-endpoint pruning, not a failure
   of the send, and the phone's endpoints are unaffected.
 
+**HOST-VERIFIED 2026-09-20 (dev login, macOS 26, imsg 0.13.0) — tapback
+failure reasons (M2B-40), gateway-side half.** Run from the packed branch build
+against a live DM: add / add-again / remove / remove-again still answer
+`{ok:true}`, `already-reacted`, `{ok:true}`, `not-reacted` for both verbs
+(1.2–1.7 s per fired call), so the success and skip shapes are unchanged by the
+new verify wiring; a guid absent from the 30-row window answers
+`{ok:false, effectStarted:false, reason:'refused'}` for add, remove and the
+emoji arm, and chat.db gained **no row**; an empty emoji answers the same; and a
+real native refusal (`rpc.tapback` on an unknown `chat_id` → `-32602`, `data:
+"unknown chat_id 999999"`) classifies `refused`, which also confirms
+`error.data` survives the rpc plumbing the classifier reads.
+
+**NOT YET HOST-VERIFIED — the helper half.** The `TAPBACK_PROVEN_REJECTIONS`
+texts are read from `IMsgInjected.m` `handleSendReaction`, not observed: none
+can be provoked without a broken host. `fire-failed`, `unverified` and
+`verify-read-failed` are unit-tested only. The one failure seen live (dev,
+2026-09-18, a tapback aimed at a group-action row: `send-reaction failed:
+-[IMGroupActionItem expressiveSendStyleID]: unrecognized selector`) classifies
+`fire-failed`, which is the conservative side.
+
+**HOST-VERIFIED 2026-09-20 (lab Mac, macOS 26.6.2, marker build, a real iPhone
+watching the thread) — tapbacks on one part (M2B-45), through these SDK verbs.**
+The native layer was already proven on real iPhones on macOS 26.6.2 and 27.0
+(Mapier-Labs/imsg `mapier/deploy` @ `b9c435f`); this run drove the gateway verbs
+themselves, against SDK `8743b22`:
+
+- `capabilities.tapbackPart` read `true` off the marker build.
+- `tapback(…, 'love', false, 1)` → `{ok:true}`, and the SAME call again →
+  `{ok:true, skipped:'already-reacted'}`. That second answer is also the
+  readback proof: the guard can only skip if the history aggregate handed it
+  `target_part: 1`, so `reactions[].target_part` is confirmed live, not just
+  in the fake.
+- `tapback(…, 'love', false, 0)` then SENT rather than skipping, although part 1
+  already carried `love` — the two do not collapse into one reaction.
+- `emojiTapback(…, '🔥', false, 1)` → `{ok:true}`: the emoji arm carries a part
+  the same way.
+- `tapback(…, 'love', true, 0)` → `{ok:true}`, removing part 0's and leaving
+  part 1's alone.
+- `partIndex: 5` on a message without it → `{ok:false, effectStarted:false,
+  reason:'refused'}`. So `'has no part '` in `TAPBACK_PROVEN_REJECTIONS` is an
+  OBSERVED classification, unlike its neighbours, which remain read-from-source.
+- `partIndex: 1.5` → refused client-side, nothing sent.
+- The chat.db rows carry a `p:N/` prefix and a range that AGREE — the shape an
+  iPhone's own per-photo tapback writes, and the one whose disagreement is what
+  the `tapbackPart` marker exists to prevent.
+
+**Still NOT host-verified for M2B-45:** the capability-OFF arm (`partIndex >= 1`
+answering `unsupported`), which cannot be provoked without running a
+pre-marker helper; removing an EMOJI tapback from a part; and the ambiguous
+failure arms (`fire-failed`, `unverified`, `verify-read-failed`) reached with a
+part, which are unit-tested only for the same reason the M2B-40 note below
+gives.
+
 **NOT YET HOST-VERIFIED — `GroupMutationResult` (M2B-40).** The reason
 vocabulary, the three-member floor and the DM preflight are derived from the
 native sources (`IMsgInjected.m` `handleAddParticipant` /
@@ -865,6 +1260,86 @@ removal; (3) do the add/remove/rename round trips still return the bare
 prints the measured membership and asserts the floor refusal, so a single run
 settles all three.
 
+**NOT YET HOST-VERIFIED — `MessageRemovalResult` (M2B-43).** The
+`UNSEND_PROVEN_REJECTIONS` / `DELETE_PROVEN_REJECTIONS` texts are read from
+`IMsgInjected.m` `handleUnsendMessage` / `handleDeleteMessage`, not observed;
+none can be provoked without a broken host. `fire-failed`, `unverified`,
+`verify-read-failed` and `preflight-read-failed` are unit-tested only
+(`tests/message-removal-failure.test.ts`), which under hard rule 1 is **not**
+proof. One run of `scripts/tier2-smoke.ts` on the host settles the two
+questions that matter: (1) do the unsend/delete round trips still answer a bare
+`{ok:true}` with the classification wiring in front of them — the smoke already
+prints the whole result object on failure, so a stray `reason` on a success
+shows up; and (2) does an out-of-window unsend now answer `unverified` where it
+used to answer `{ok:true}`. That second one is a **behavior change, not just a
+new field**: the old verify predicate (`!found?.text`) read an absent row as a
+cleared one, so an unsend whose guid was outside the 30-row window — or merely
+lagging history — reported a success nobody had observed. FakeGateway already
+refused that input, so the fake and the real gateway disagreed on it until now.
+
+**NOT YET HOST-VERIFIED — `sendExtensionCard` (M2B-46).** The native half is
+proven: on 2026-09-20 a Mac-injected card for a non-Apple iMessage extension
+sent, delivered, drew, opened the installed app in-thread, and updated in place
+on real phones (macOS 26.6.2 and 27.0) — that run is where the first-card rule
+comes from. **The SDK verb has not run against a host Mac.** Everything in it
+is derived from the native sources (`RPCServer+ExtensionCardHandler.swift`,
+`ExtensionCardRequest.swift`, `IMsgExtensionCard.m`, `IMsgInjected.m`
+`handleSendExtensionCard`) and covered by unit tests and the fake
+(`tests/extension-card.test.ts`), which under hard rule 1 is **not** proof, and
+under rule 2's §4 contributor rule this stays forbidden surface until the host
+run lands. One run settles the three questions that matter: (1) does a first
+send actually come back carrying a `guid` — the whole `updatable` distinction
+exists because the handler omits it when Messages has not exposed one, and how
+often that happens is unmeasured; (2) does an update driven by the *returned*
+handle restamp the first card rather than adding a row, i.e. does the handle
+round trip survive the SDK's UUID validation of real Messages guids; and (3) do
+both markers read `true` on the current build — a host with `extensionCardSend`
+and not `extensionCardUpdate` is possible by construction but has never been
+seen. There is no smoke leg for this verb yet; the host proof is driven by hand.
+
+**HOST-VERIFIED 2026-09-21 (lab Mac, macOS 26.6.2) — `sendMultipart` (M2B-55),
+through this SDK verb.** The native layer was already proven on a real iPhone
+the same day through the native CLI (Mapier-Labs/imsg#28): ten shapes — caption
++ photo, photo + caption, caption + 3 photos, alternating text and photos, two
+text parts, five photos, a 93 MiB ten-photo message — each arriving as a single
+notification with the parts in the order given and the photos stacked, which is
+where the "no trailing newline" and "consecutive text parts are fine" rules come
+from, and where the phone RENDERING of these shapes is settled. This run drove
+the gateway verb itself: the packed tarball of SDK `43b6454` installed into a
+scratch dir, `IMSG_BIN` pointed at the native build of imsg#28 head `f2a8bc6`
+(helper sha256 `3229d9dd…`). The phone rendering was not re-judged per SDK
+send — these legs prove the SDK's half, and `chat.db` is the oracle for it:
+
+- `capabilities.multipartSend` and `capabilities.mentionFormatting` both read
+  `true` off that build.
+- `[text, file, file, text]` → `{ok:true, guid, partCount:4}`, and that guid is
+  **ONE** `chat.db` row with `part_count` 4, **two attachment joins**,
+  `is_sent` 1, `is_delivered` 1, `error` 0. That pair is the load-bearing
+  observation of the whole verb: a `partCount` of 4 arriving with both photos
+  actually joined is the direct evidence that the file parts were not silently
+  dropped — the failure the `multipartSend` marker exists to prevent, until now
+  reasoned from the helper's source rather than seen.
+- `[text with a bold range, file]` with `effect` and `subject` →
+  `{ok:true, guid, partCount:2}`; ONE row, `part_count` 2, one attachment,
+  the subject set, and `expressive_send_style_id`
+  `com.apple.messages.effect.CKConfettiEffect`, sent and delivered, `error` 0.
+  So the per-part `text_formatting` and the message-wide `effect` / `subject`
+  survive this SDK's wire shape into the fields the native handler's
+  `send.rich` parsers write.
+- An empty list, a 41-file list, and `textFormatting` on a file part each
+  answered `{ok:false, effectStarted:false, reason:'refused'}` — and the run
+  wrote **exactly two rows in total**, so all three refusals fired nothing.
+  That row count is the only way to prove `effectStarted:false`, which is a
+  claim about what did NOT happen.
+
+**Still NOT host-verified for M2B-55:** a confirmed mention inside a multipart
+text part (it needs a group thread, and the marker reading `true` is not the
+same as a mention landing); `replyToGuid` as an inline-reply target; and every
+string in `MULTIPART_PROVEN_REJECTIONS` — no send failed on the host, so the
+fire-failure classifier stays read-from-source and unit-tested only, unlike
+M2B-45's `'has no part '`, which its run happened to provoke. There is still no
+smoke leg for this verb; the host proof is driven by hand.
+
 - **subscribe(sinceId?)** — long-lived event stream of new messages/reactions across all
   chats the host Mac's Messages account can see. `sinceId` is an **exclusive** cursor: only
   events with `id > sinceId` are delivered (catch-up semantics, not "starting at"). Today
@@ -946,7 +1421,9 @@ fail closed (covered by `tests/imsg-rpc.test.ts`).
   recent 30 messages are scanned (the real path reads `history(chatId, 30)`) — a tapback on
   an older message is invisible, and FakeGateway enforces the same window so features can't
   be built against reach the real gateway doesn't have. Feeds "[reacted X to your message]"
-  acknowledgment notes into agent context.
+  acknowledgment notes into agent context. A note carries `targetPart` when they reacted to one
+  part of our message (M2B-45) — 1 is the second photo of two — and carries no such key at all
+  when they reacted to the whole message.
 - **resolveDmChat(handle)** — the numeric `chat_id` of the existing DM thread with `handle`, or
   `null` if none exists. **Read-only** — it must never create a thread (the real path reads
   `chat.db` via `chats.list` and cannot mint one; FakeGateway may not exceed that). The runtime
@@ -1010,7 +1487,11 @@ a different product.
   (2026-07-02) and imsg 0.12.3 (2026-07-07): `messages.history` returns no `is_reaction` rows
   (they'd duplicate the reacted
   message), but every message carries a `reactions[]` aggregate — the current tapback state on
-  that bubble: `{ id, type, emoji?, is_from_me, sender?, created_at? }` per reaction.
+  that bubble: `{ id, type, emoji?, is_from_me, sender?, created_at?, target_part? }` per reaction.
+  `target_part` (M2B-45) is which PART of the message the reaction named, and is absent when it
+  named the whole message — read it through `reactionPart()`, never directly, or "loved the
+  message" and "loved photo 1" look like different targets. One sender can hold the same
+  reaction type on two parts, and that is two entries, not one.
   Consequence: reaction-state logic (toggle guard, `recentReactions`) reads history — it is
   authoritative and restart-safe. The subscribe stream (`include_reactions: true`) still
   delivers reaction EVENTS for realtime wake-ups, but is never the source of state: a process
@@ -1213,6 +1694,35 @@ a different product.
   messages, reacting to an arbitrary (non-most-recent) message, and participant management
   on an existing group (add/remove/rename/photo/leave).
 
+- **An extension-card update aimed at the wrong card cannot be detected, and
+  FakeGateway must not detect it either** (M2B-46). Every update in a session
+  has to name that session's FIRST card; pointing one at a previous update's
+  guid produces a separate card that is never replaced, with `ok:true`, a real
+  guid and a delivery. The Mac has no way to catch it — it does not know which
+  guid began a session — so a fake that rejected a hand-built handle would test
+  consumers against a safety net that does not exist on the host. The
+  protection lives in the API shape instead: `sendExtensionCard` takes only an
+  `ExtensionCardHandle` it minted, and returns that same handle unchanged from
+  every update, so carrying `result.handle` forward stays correct. Both
+  implementations also refuse to invent a guid: when Messages exposes none, the
+  success carries `updatable:false` and no handle rather than a synthesized one.
+
+- **A multipart send is ONE row, and the fake may under-count its parts —
+  never over-count** (M2B-55). `sendMultipart` emits a single outbound row on
+  both implementations, whatever the part list holds: one notification, one
+  `chat.db` row, several bubbles. What the fake does not do is synthesize that
+  row's inner shape. The real row's `text` is Apple's own concatenation of the
+  parts with object-replacement placeholders where the files sit, and its
+  `attachments[]` only appears on a later history/watch row — the send response
+  reports neither, and inventing them is exactly what `sendAttachment` already
+  refuses to do. The consequence is deliberate: `FakeGateway.partCount()` still
+  counts attachments, so a fake-sent multipart row reports 1 part however many
+  it really had, and a part-level tapback on it is refused where a host would
+  accept it. That is the allowed direction (the fake must not succeed at what
+  the real path refuses), and counting `(text ? 1 : 0) + attachments.length`
+  instead is a contract change that needs the host run to prove the real part
+  layout first.
+
 - **Inbound media.** Real messages can carry `attachments[]` with empty `text`. FakeGateway must
   be able to emit the exact attachment metadata with `text: undefined`/empty so
   this path gets exercised — the agent currently ignores attachments gracefully
@@ -1295,7 +1805,9 @@ harness (`tsx --test`, see `package.json`). Required cases:
   `ok:false` without mutation
 - `tapback`/`editMessage`/`unsendMessage`/`deleteMessage` all return `ok: false` — without
   mutating anything — for a guid outside the 30-message scan window (the guid-targeting
-  window above), even though the message still exists in the fake's full store
+  window above), even though the message still exists in the fake's full store, and all
+  four say `effectStarted:false` because the fake never fires (the real
+  `unsendMessage` answers `unverified` for that input: it fires first)
 - `sendRich` sends to an existing chat with an inline reply target, and returns `ok: false`
   for a chat that doesn't exist (no find-or-create, unlike `send`)
 - `sendRich` accepts a subject while preserving the observable text echo (subject is
@@ -1321,8 +1833,16 @@ harness (`tsx --test`, see `package.json`). Required cases:
   mutation when the `editMessage` capability marker is absent
 - `unsendMessage` retracts the target row (text clears, row persists);
   `deleteMessage` is dispatch-only with no stable history postcondition (the
-  fake conservatively preserves the row); both return `ok: false` for an
-  unknown guid
+  fake conservatively preserves the row); both name an unknown guid as
+  `ok:false, effectStarted:false, reason:'refused'`
+- (real-path only, `tests/message-removal-failure.test.ts` over the pure
+  module) for both removal verbs a bridge rejection raised before IMChat is
+  `refused` and a timeout, an unmodelled `-32603` or a non-rpc error is
+  `fire-failed`, with one verb's proven-rejection text not excusing another's;
+  `deleteMessage`'s pre-check names an exhausted poll `refused` and a thrown
+  read `preflight-read-failed`; `unsendMessage`'s read-back names an exhausted
+  verify window `unverified` — including a guid it never sees, which must not
+  be mistaken for a cleared row — and a thrown read `verify-read-failed`
 - `setTyping`/`markRead` dispatch `{ ok: true }` against an existing chat and `{ ok: false }`
   against an unknown one, with no queryable state either way
 - `renameGroup`/`addParticipant`/`removeParticipant` are reflected in a message sent
@@ -1356,6 +1876,20 @@ harness (`tsx --test`, see `package.json`). Required cases:
 - `sendLocationRequest` posts the card as its own outbound row to an existing chat, returns
   the balloon guid, refuses an unknown chat (no find-or-create), and fails closed without
   the `locationRequest` marker (no row written)
+- `sendExtensionCard` posts the card as its own outbound row to an existing chat, composes
+  the balloon id from the team and extension ids, hands back a `handle` whose
+  `firstCardMessageGuid` is that row, and keeps returning that SAME handle through three
+  chained updates (each its own row); bad input and an unknown chat are `refused` with no
+  row written, a missing `extensionCardSend` marker is `unsupported`, and a host with
+  `extensionCardSend` but not `extensionCardUpdate` sends but refuses the update. One case
+  asserts a NEGATIVE: an update aimed at a previous update's guid is **not** caught — the
+  fake must not be safer than the Mac, which cannot detect it either
+- `sendMultipart` lands text and file parts as ONE outbound row (not one per part), reports
+  the host's `partCount` and a guid, and preserves an inline-reply guid alongside the
+  message-wide effect and subject; an empty list, an empty text part, formatting on a file
+  part, 41 file parts and an unknown chat are each `refused` with no row written, and a
+  missing `multipartSend` marker is `unsupported` — including for a text-only list, which
+  such a host could actually have sent
 - Fake-only restart coverage snapshots and restores a world, then proves
   `sendStatus`, `checkHandle`, Name & Photo idempotency, chat backgrounds (and their
   guid sequence), Find My shares, current group metadata, fixture state, and monotonic IDs