@mapier/imsg-sdk 0.4.0 → 0.6.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,8 @@ interface Gateway {
     mentionFormatting: boolean;
     sharedLocations: boolean;
     locationRequest: boolean;
+    extensionCardSend: boolean;
+    extensionCardUpdate: boolean;
   };
   subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
   history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
@@ -78,8 +81,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,19 +112,24 @@ 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>;
   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<{ ok: boolean }>;
+  renameGroup(chatId: number, name: string): Promise<GroupMutationResult>;
   setGroupPhoto(chatId: number, filePath?: string): Promise<{ ok: boolean }>;
-  addParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
-  removeParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
+  addParticipant(chatId: number, handle: string): Promise<GroupMutationResult>;
+  removeParticipant(chatId: number, handle: string): Promise<GroupMutationResult>;
   leaveGroup(chatId: number): Promise<{ ok: boolean }>;
   shareNamePhoto(chatId: number): Promise<{
     ok: boolean;
@@ -189,6 +209,63 @@ interface GroupChatResolutionRequest {
   expectedParticipantExternalIds: readonly string[];
   excludedParticipantExternalIds?: readonly string[];
 }
+
+// renameGroup / addParticipant / removeParticipant. A success is proven (read
+// back from a fresh chats.list) and carries neither field. Every failure
+// carries both, and `effectStarted` follows from `reason` alone.
+interface GroupMutationResult {
+  ok: boolean;
+  effectStarted?: boolean;
+  reason?:
+    | 'unsupported'         // capability marker absent       — effectStarted:false
+    | '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
+    | '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
+}
 ```
 
 ### Tier 2 (bridge-backed)
@@ -224,6 +301,10 @@ 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).
 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
@@ -236,11 +317,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
@@ -248,7 +335,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
@@ -262,13 +349,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
@@ -366,6 +528,70 @@ 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.
 - **`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
@@ -418,6 +644,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
@@ -432,7 +700,63 @@ prevent.
   The long-lived RPC process keeps a stale chat-metadata view after its own
   mutation on macOS 26, while a fresh `imsg chats` process sees the update.
   Verification therefore polls fresh, read-only CLI processes (using the
-  same `IMSG_BIN`) for up to 20 seconds before returning `ok:false`.
+  same `IMSG_BIN`) — `GROUP_MUTATION_VERIFY_ATTEMPTS` (20) × 1 s, so a
+  **20-second** window — before giving up.
+
+  **A failure says which failure it is** (`GroupMutationResult`, M2B-40).
+  These three verbs used to answer a bare `ok:false` whether nothing had
+  fired or the mutation had gone out unconfirmed, which left a consumer no
+  choice but to settle every failure as possibly-applied — un-retirable
+  reconciliation work by construction. The classification, in the order the
+  gateway reaches it:
+
+  - **`unsupported`** (`effectStarted:false`) — `addParticipant`/
+    `removeParticipant` without the `groupParticipants` marker. Nothing was
+    called and no request on this host build ever could be.
+  - **`refused`** (`effectStarted:false`) — a proven rejection before IMChat
+    was invoked. Either the gateway's own preflight (target is a DM; the
+    removal would break the member floor below) or the helper's: a `-32602`,
+    or a `-32603` whose `error.data` carries one of that verb's known
+    pre-invoke refusals (`Chat not found`, `Could not vend handle`,
+    `Participant not found on chat`, `_setDisplayName: not available`, the
+    missing-selector and missing-parameter texts). The lists are per verb, in
+    `gateway/group-mutation.ts`, and are matched the same way the
+    chat-background pair matches its own.
+  - **`fire-failed`** (`effectStarted:true`) — the mutation call errored but
+    the error does NOT prove the helper stopped short: a bridge timeout, an
+    exception raised after IMChat was invoked, a dead rpc child, any
+    unmodelled `-32603`. It may already have applied.
+  - **`unverified`** (`effectStarted:true`) — it fired cleanly and the 20 s
+    window closed with `chats.list` never showing the wanted state.
+  - **`verify-read-failed`** (`effectStarted:true`) — it fired cleanly and
+    then the verification read itself failed, so there is no evidence either
+    way. One failed read ends the wait (it always has): `imsg chats` is a
+    local chat.db read, so a failure means a broken host, not a blip. Kept
+    distinct from `unverified` because the remediation is an operator's, not
+    a retry.
+
+  A success stays the bare `{ok:true}` it has always been: it was read back
+  from chat.db, so neither field would add anything.
+
+  **Apple's three-member floor.** A group conversation stays at three or more
+  members, the local user included; Apple silently declines a removal that
+  would drop it below that — `removeParticipants:reason:` returns normally and
+  the membership does not change. There is no error to classify, so
+  `removeParticipant` counts first: one fresh `chats.list` read before firing,
+  and a group whose `participants[]` (which excludes the local user, so the
+  group has `participants.length + 1` members) is shorter than
+  `GROUP_MIN_MEMBERS` is `refused` outright instead of costing the full 20 s
+  and then reporting ambiguity. The same read refuses a DM target for all
+  three verbs, which the bridge likewise answers by doing nothing.
+
+  Both preflight rules are **best-effort and fail open**: only what that read
+  actually reported is acted on. A chat outside `CHAT_SCAN_LIMIT`, a read that
+  failed, a row without the field, or a membership list that no longer
+  contains the target handle all fall through to fire-and-verify. An unknown
+  target must never become a confident refusal — the same discipline
+  `participant_directory_unavailable` applies in `resolveGroupChat`. Trusting
+  the count only when the target is still listed is what keeps a stale
+  chat.db view from refusing a removal that would have worked.
 - **`setGroupPhoto`/`leaveGroup`** — `group.setIcon` / `group.leave`. No field
   in imsg's JSON output reflects a group photo, and `participants[]` always
   excludes the local user (see "Participants exclude the local user" above),
@@ -779,6 +1103,112 @@ 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` /
+`handleRemoveParticipant` / `handleSetDisplayName`,
+`RPCServer+ChatHandlers.swift` `invokeBridge`) and are covered by unit tests,
+which under hard rule 1 is **not** proof: `imsg` exit codes lie and Messages.app
+cannot be faked. Before this ships, `scripts/tier2-smoke.ts --group-chat-id
+<group> --participant <handle>` has to run on the host and answer three
+questions: (1) does a removal at the floor actually get refused by Apple, or
+does it land — the whole preflight is wrong if it lands; (2) is the floor three
+members counting the local user, i.e. does a 4-member group allow exactly one
+removal; (3) do the add/remove/rename round trips still return the bare
+`{ok:true}` they did before the preflight read was added. The smoke's group leg
+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.
+
 - **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
@@ -860,7 +1290,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
@@ -924,7 +1356,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
@@ -1035,6 +1471,28 @@ a different product.
     There is no "create empty group". Adding/removing a member on an *existing* group is possible —
     see "Tier 2" above (`addParticipant`/`removeParticipant`, bridge-backed) — but only through
     those methods, not through `createGroup`.
+  - **A group never shrinks below three members.** Apple keeps a group
+    conversation at `GROUP_MIN_MEMBERS` (3) or more, counting the local user,
+    and silently declines any removal that would break that — no error, no
+    change. So `removeParticipant` on a group whose `participants[]` (local
+    user excluded, see "Participants exclude the local user") is shorter than
+    three is `{ok:false, effectStarted:false, reason:'refused'}` and nothing
+    is fired. FakeGateway models the floor too: a fake that happily shrinks a
+    group to two exceeds what the real gateway can do, and fixtures built on
+    it would rehearse a removal iMessage refuses.
+  - **A group mutation that failed says where it failed.** `renameGroup`,
+    `addParticipant` and `removeParticipant` return `GroupMutationResult`
+    (§1): a failure always carries `reason` and the `effectStarted` that
+    follows from it, so a proven no-op is settled as a clean failure and only
+    a mutation that actually reached IMChat is reconciled. The reason
+    vocabulary and the per-verb proven-rejection lists are under "Tier 2"
+    above. FakeGateway reaches only the proven-no-op half (`unsupported`,
+    `refused`) — it has no bridge to time out on and must never manufacture
+    an `effectStarted:true` that would send a consumer off to reconcile a
+    mutation that never existed. Removing a handle the chat does not list is
+    one of those refusals on both sides: the helper matches against the live
+    IMChat participant list and answers `Participant not found on chat`,
+    so the fake must not model it as a silent success either.
   - **Compose guard**: if Cmd+N fails to enter compose (sibling of the react Cmd+T failure,
     observed live 2026-07-17), every scripted keystroke would land in the focused chat's
     compose field and each Return would send it — recipient handles texted into an open
@@ -1105,6 +1563,19 @@ 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.
+
 - **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
@@ -1187,7 +1658,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
@@ -1213,15 +1686,33 @@ 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
-  afterward (`chat_name`/`participants`) and return `ok: false` against a DM
+  afterward (`chat_name`/`participants`); a DM target is the proven
+  `{ok:false, effectStarted:false, reason:'refused'}`, and so is a removal that
+  would break Apple's three-member floor or that names a handle the chat does
+  not list — in both cases the membership is untouched afterward
 - `setGroupPhoto`/`leaveGroup` return `ok: true` against a group and `ok: false` against a DM
 - patched sticker, group-photo, participant, and chat-background verbs return `ok:false`
-  without mutation when their `imsg status` capability markers are absent
+  without mutation when their `imsg status` capability markers are absent; the
+  participant verbs name it `reason:'unsupported'`, distinct from a request the
+  host declined
+- (real-path only, `tests/group-mutation.test.ts` over the pure module) a bridge
+  rejection raised before IMChat is `refused`; a timeout, an unmodelled `-32603`
+  or a non-rpc error is `fire-failed`; an exhausted verify window is
+  `unverified`; a failed verification read is `verify-read-failed` — one verb's
+  proven-rejection text does not excuse another's
 - chat background: `setChatBackground` persists a NEW guid on a DM and a group (a re-set
   changes the guid), `chatBackgroundStatus` reflects it, `removeChatBackground` clears it;
   remove on a bare chat is the explicit `no-background` skip (also with an empty guard), a
@@ -1238,6 +1729,14 @@ 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
 - 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