@mapier/imsg-sdk 0.2.0 → 0.2.2

package/docs/gateway-contract.md

@@ -0,0 +1,818 @@
+# Gateway contract — ImsgGateway ↔ FakeGateway
+
+## Purpose
+
+`Gateway` is the only boundary between the agent and iMessage. Two implementations:
+
+- **ImsgGateway** — real. Wraps `openclaw/imsg` (JSON-RPC subprocess + CLI) running on the
+  host Mac. See `docs/host-mac-control.md` for how that host is reached and configured.
+- **FakeGateway** — dev/simulator/eval. No Mac, no `imsg` binary, no Messages.app.
+
+Most development happens against FakeGateway, with no way to check behavior against real
+iMessage in the loop. That makes FakeGateway's fidelity the whole ballgame: if it lies about
+what iMessage does, every feature built against it either breaks on the host Mac or, worse,
+assumes a capability iMessage doesn't have.
+
+Two rules follow:
+
+1. **FakeGateway must reproduce every behavioral invariant in §2.** Not "close enough" —
+   exact, including the annoying ones (id monotonicity, reaction toggling, most-recent-only
+   targeting).
+2. **FakeGateway may never offer more capability than ImsgGateway.** If the real `imsg` CLI
+   can't do it, FakeGateway must not let the agent do it either. A capability that only exists
+   in the fake is a trap: code gets built against it, then breaks the first time it touches a
+   real Mac.
+3. **Fidelity is about SETUP, not just messaging.** The trap in rules 1–2 also springs from the
+   *state a user can be in*, not only the operations we can run. Any sim tool that fabricates a
+   user (dev-mint, god-mode create — `docs/sim-dev-tools.md`) must land them in a state a real
+   user could actually reach: a real user reaches onboarding *because they texted the prefill
+   first*, so their DM thread exists before any link completes. A sim shortcut that mints a link
+   for a never-texted user puts them in an impossible state and makes green sim runs lie about
+   prod. When you add a setup shortcut, ask "could a real user be here?" — if not, seed whatever
+   the real arrival would have created (e.g. the DM thread via `gateway.ensureDm`), or the test
+   is a fiction.
+
+Conformance is enforced by one shared contract test suite (§4) parameterized over both
+implementations. Against FakeGateway it runs in normal CI. Against ImsgGateway it runs on the
+host Mac — manual today, CI-optional once that runner exists.
+
+Ground truth: the invariants below were verified live against **imsg 0.12.0** on the host Mac
+(2026-07-02 conformance smoke, `scripts/live-smoke.ts`) and re-verified against **imsg 0.12.3**
+(2026-07-07 upgrade smoke, `scripts/live-smoke.ts 3996`). Earlier drafts cited imsg's docs;
+where the live binary disagreed with a docs reading (reaction state in history,
+`chats.list` field names), the live behavior below is authoritative.
+
+Read-only gateway changes may use `scripts/live-smoke.ts <chatId> --read-only` when
+Messages.app UI automation is unavailable. That mode verifies history, portable chat
+directory, bounded attachment-aware history, and end-bound filtering only; it makes no
+claim about send, reaction, or group mutation behavior.
+
+## 1. Interface
+
+```ts
+interface Gateway {
+  readonly capabilities: {
+    emojiTapback: boolean;
+    stickerSend: boolean;
+    groupPhoto: boolean;
+    groupParticipants: boolean;
+    namePhotoSharing: boolean;
+  };
+  subscribe(sinceId?: number): AsyncIterable<GatewayEvent>;
+  history(chatId: number, limit?: number): Promise<ImsgMessage[]>;
+  listChats(limit?: number): Promise<GatewayChat[]>;
+  historyRange(chatId: number, range: GatewayHistoryRange): Promise<ImsgMessage[]>;
+  send(target: { chatId: number } | { to: string }, text: string): Promise<SendResult>;
+  react(chatId: number, reaction: Reaction, expectedGuid?: string): Promise<ReactResult>;
+  createGroup(handles: string[], firstMessage: string): Promise<{ chatId: number }>;
+  recentReactions(chatId: number, limit?: number): Promise<ReactionNote[]>;
+  resolveDmChat(handle: string): Promise<number | null>;
+  resolveGroupChat(request: GroupChatResolutionRequest): Promise<GroupChatResolution>;
+  sendStatus(guid: string): Promise<SendStatus>;
+  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>;
+  sendRich(
+    chatId: number,
+    text: string,
+    opts?: { effect?: string; replyToGuid?: string; subject?: string },
+  ): Promise<SendResult>;
+  sendAttachment(
+    chatId: number,
+    filePath: string,
+    opts?: { audio?: boolean; replyToGuid?: string },
+  ): Promise<SendResult>;
+  sendSticker(
+    chatId: number,
+    filePath: string,
+    opts?: { attachToGuid?: string; partIndex?: number },
+  ): Promise<SendResult>;
+  sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
+  sendRichLink(chatId: number, url: string): Promise<SendResult>;
+  editMessage(chatId: number, targetGuid: string, text: string): Promise<{ ok: boolean }>;
+  unsendMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
+  deleteMessage(chatId: number, targetGuid: string): Promise<{ ok: boolean }>;
+  setTyping(chatId: number, on: boolean): Promise<{ ok: boolean }>;
+  markRead(chatId: number): Promise<{ ok: boolean }>;
+  renameGroup(chatId: number, name: string): Promise<{ ok: boolean }>;
+  setGroupPhoto(chatId: number, filePath?: string): Promise<{ ok: boolean }>;
+  addParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
+  removeParticipant(chatId: number, handle: string): Promise<{ ok: boolean }>;
+  leaveGroup(chatId: number): Promise<{ ok: boolean }>;
+  shareNamePhoto(chatId: number): Promise<{
+    ok: boolean;
+    skipped?: 'not-offered';
+    effectStarted?: boolean;
+  }>;
+}
+
+interface ReactionNote {
+  id: number; // the reaction's global rowid
+  // 'custom' covers an arbitrary-emoji tapback (iOS 18+, imsg surfaces it as
+  // type "custom" with the real emoji in `emoji`). Sending requires the
+  // patched-fork emojiTapback capability.
+  reaction: Reaction | 'custom';
+  emoji?: string;
+}
+
+interface ReactResult {
+  ok: boolean;
+  skipped?: 'already-reacted' | 'stale-target' | 'not-reacted';
+}
+
+type GatewayEvent = ImsgMessage; // message or reaction; see §2 shape
+
+type Reaction = 'love' | 'like' | 'dislike' | 'laugh' | 'emphasis' | 'question';
+
+interface SendResult {
+  ok: boolean;
+  id?: number;
+  guid?: string;
+}
+
+interface GroupChatResolutionRequest {
+  conversationExternalId: string;
+  expectedParticipantExternalIds: readonly string[];
+  excludedParticipantExternalIds?: readonly string[];
+}
+```
+
+### Tier 2 (bridge-backed)
+
+Everything below requires the IMCore bridge (`imsg launch`, SIP disabled — see
+`docs/imsg-polls.md` for the host setup and `docs/host-mac-control.md`).
+These operations, including the primary `createGroup()` path, do not drive
+Messages.app UI automation: they call the injected dylib's private IMCore API directly
+through openclaw's per-request v2 IPC queue (built for concurrent access), so
+`ImsgGateway` does not serialize them through the UI-automation Mutex. All of
+them are wired over the long-lived `imsg rpc` child (`src/imsg/rpc.ts`), the
+same transport as `send`/`history`/`chats.list` — openclaw exposes every verb
+below as a JSON-RPC method (confirmed against openclaw's `RPCServer.swift`
+`kSupportedRPCMethods` dispatch table and `docs/rpc.md` "Bridge Message
+Actions"), so none of it needed a new `execFile` CLI subprocess.
+
+**Patched-fork capability discovery.** Stock imsg can advertise the same RPC
+method names while still lacking Mapier's macOS-26 fixes and custom `emoji`
+parameter. `ImsgGateway` therefore uses `IMSG_BIN` (falling back to `imsg`) for
+both the long-lived RPC process and its one-time `status --json` probe.
+Patched verbs require the injected bridge's explicit selector markers
+`emojiTapbackSend`, `stickerSend`, `groupPhotoUpdate`, `groupAddParticipant`, and
+`groupRemoveParticipant`; Name & Photo requires both `namePhotoShouldOffer`
+and `namePhotoShare`; 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.
+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
+the capability descriptor it actually negotiated; the presence of a gateway
+method on a wire never enables a feature by itself.
+
+**Guid-targeting window.** `tapback`, `editMessage`, `unsendMessage`, and
+`deleteMessage` can target ANY message guid, but `ImsgGateway` locates that
+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; `editMessage`/`unsendMessage` fire
+the RPC first and only find 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
+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
+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 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
+  automation `react()` depends on); explicit add/remove instead of toggle.
+  What it does **not** add by itself: an arbitrary/custom emoji. openclaw's own bridge
+  handler (`RPCServer+BridgeMessageHandlers.swift` `handleTapback` →
+  `normalizeBridgeReactionType`, backed by the closed `BridgeReactionKind` enum
+  in `IMsgBridgeProtocol.swift` and the `kindMap` in the injected
+  `IMsgInjected.m` `handleSendReaction`) accepts only the same 6 canonical
+  kinds `react()` does, and openclaw's own CHANGELOG documents this as
+  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
+  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`.
+- **`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
+  **existing** chat only — unlike `send()` there is no `{ to: handle }`
+  find-or-create form. `opts.effect` is a Messages expressive-send effect
+  short name; valid values are bubble `impact`, `loud`, `gentle`, `invisibleink` and
+  screen `confetti`, `lasers`, `fireworks`, `balloons`, `sparkles`, `spotlight`,
+  `echo`, `love`, `celebration`. `opts.replyToGuid` sets an inline reply target;
+  `opts.subject` sets the Messages subject line. Subject is write-only through
+  this Gateway because `ImsgMessage` has no subject field. The `url` submode is
+  exposed separately as `sendRichLink` because openclaw treats URL and
+  text/subject/effect/reply as mutually exclusive modes.
+- **`sendAttachment(chatId, filePath, opts?)`** — `send.attachment`
+  (`handleSendAttachment`). Targets an **existing** chat only. `opts.audio:true`
+  sends the file as a native voice-note bubble; `opts.replyToGuid` sets an
+  inline reply target. A successful send echoes an outbound row, but file
+  content and audio mode are not asserted from the synchronous send response.
+  Attachment metadata may later appear on history/watch rows through the
+  read-side `attachments[]` shape described below.
+- **`sendSticker(chatId, filePath, opts?)`** — patched-fork `send.sticker`,
+  selector-gated by `stickerSend`. Targets an **existing iMessage chat only**;
+  there is no find-or-create form. It accepts PNG/APNG/GIF/JPEG files up to
+  500 KiB, 618×618, and 100 frames, and can optionally attach to a message guid/part.
+  Success maps the always-present `transfer_guid` to `SendResult.guid`.
+  FakeGateway conservatively echoes an outbound row but does not claim file
+  validity or rendered sticker metadata, which the send response cannot verify.
+  **Host-verified 2026-07-14/15 — delivers.** Initially failed
+  `{"error":"Dylib error: Could not securely open sticker directory"}`: the
+  injected dylib's sticker secure-open fd-walk started at the home directory,
+  which the Messages sandbox EPERMs (`open("/Users/…")` denied). Fixed in the
+  fork (`mapier/deploy`, "sticker sandbox-safe secure-open") by anchoring
+  the per-component `O_NOFOLLOW`+uid walk at the shallowest sandbox-openable
+  ancestor instead of home. After rebuild+inject, `send.sticker` delivers — a
+  real sticker row lands with `is_sticker=1, is_sent=1, error=0`.
+- **`checkHandle(address, opts?)`** — bridge-backed Apple IDS reachability via
+  `handles.check`; iMessage only, never SMS. FakeGateway returns available only
+  from evidence it actually owns: participants of known chats or an explicit
+  test/sim reachability override. A well-formed address with no evidence returns
+  `available:false`/`idStatus:0`. This deliberately under-claims users Apple IDS
+  might find reachable rather than inventing reachability the fake cannot know.
+  **Host-verified 2026-07-14 (both branches):** a real iMessage test phone →
+  `available:true, id_status:1`; an unregistered number → `available:false,
+  id_status:0`. The live false-branch confirms the fake's evidence-based model
+  is faithful, not an over-claim.
+- **`sendPoll(chatId, question, options)`** — `poll.send`
+  (`handlePollSend`), targeting an **existing** chat only and requiring at
+  least two options. The RPC's `guid` becomes `SendResult.guid` (the fork
+  docs' earlier `messageGuid` name was wrong — see the ledger below), which
+  identifies the balloon row. Poll creation has a real readback postcondition:
+  the balloon and caption rows described under "Native poll readback" below.
+- **`sendRichLink(chatId, url)`** — the `send.rich` URL submode
+  (`handleSendRichLink`), targeting an **existing** chat only. The caller
+  supplies only the bare URL; the bridge builds the preview title/image from
+  the page. **The submode is queued/async: it returns `{ ok, queued }` with NO
+  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.
+- **`editMessage(chatId, targetGuid, text)`** — `message.edit`
+  (`handleMessageEdit`). **Edits mutate the existing row's text IN PLACE: no
+  new row, no `subscribe()` event.** `MessageWatcher`'s cursor is a ROWID
+  high-water mark (`WHERE ROWID > cursor`), so an UPDATE to an existing row is
+  structurally invisible to the watch stream — the only way to observe an
+  edit is re-reading `history()` and comparing text for a guid you already
+  have. This is a new invariant: elsewhere in this doc "same guid" has meant
+  "same immutable content" (e.g. poll rows); edited messages break that.
+- **`unsendMessage`/`deleteMessage(chatId, targetGuid)`** — `message.unsend`
+  (`retractMessagePart:`) / `message.delete` (`deleteChatItems:`), two
+  distinct native APIs. **Live-verified on the host Mac:** unsend retracts in
+  place (row persists and text clears); delete dispatches successfully but
+  has no stable `history()` postcondition (the row persisted in one live run
+  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.
+- **`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
+  imsg message fields per `docs/json.md`, but the Gateway does not model them
+  as a verification surface. `ok: true` means
+  "the RPC call was dispatched without error," never "confirmed."
+- **`renameGroup`/`addParticipant`/`removeParticipant`** — `group.rename`
+  (`setDisplayName`) / `group.addParticipant` / `group.removeParticipant`
+  (`RPCServer+ChatHandlers.swift`). Verified against `chats.list`'s
+  `display_name`/`participants` fields — the same source `createGroup`'s
+  content-verify and `resolveDmChat` already read via `ImsgRpc.chats()`.
+  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`.
+- **`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),
+  so leaving never changes anything queryable either — both are
+  fire-and-forget through the Gateway, same caveat as `setTyping`/`markRead`.
+  The patched host path is **receiver-verified** (2026-07-15, iMessage group →
+  the icon rendered on the recipient device). The fork **stages** the image
+  into the Messages Attachments tree (`stageAttachment`) before transferring it
+  via `createNewOutgoingGroupPhotoTransferWithLocalFileURL:`, then persists an
+  `at_0_...` group-photo GUID, posted as a silent group-action event with no
+  attachment bubble. Staging is load-bearing: an unstaged path is unreadable by
+  sandboxed imagent, so the GUID binds locally but the file never uploads (no
+  attachment row, no delivery — the original failure). A custom emoji /
+  solid / gradient icon is just a rendered PNG sent through this same path — no
+  special API.
+  **`leaveGroup` is currently dead on the live host** (observed 2026-07-17,
+  macOS 26.5.1, fork 0.13.0): `group.leave` returns `-32603 Internal error`
+  regardless of group size, and `imsg status` lists no leave-related selector
+  (its neighbors `deleteChat`/`editMessage` are also ✗ on this build). The
+  gateway degrades to `{ ok: false }`. Treat leave as unavailable until the
+  fork restores the selector; imsg-sdk issue #5 tracks it.
+
+All Tier-2 group-management methods reject a DM `chatId` (`ok: false`) on
+both implementations — none of Apple's group primitives apply to a 1:1 chat.
+
+- **`shareNamePhoto(chatId)`** — Apple Messages' native **Share Name & Photo**
+  flow, not a vCard or Contacts attachment. It first calls
+  `contacts.shouldShareContact` and requires `available:true` plus
+  `should_offer:true`; otherwise it fails or returns the idempotent
+  `skipped:"not-offered"`. Only then does it call
+  `contacts.shareContactCard`, and success requires `requested:true`. The
+  result carries `effectStarted:false` for a preflight failure and
+  `effectStarted:true` when the RPC share invocation began but did not return a
+  verified success. A consumer maps the latter to reconciliation instead of
+  claiming the effect never started. The
+  runtime invokes this once per process on the first allowlisted inbound text
+  in a DM; reaction-only and blocked senders never trigger it. That process
+  guard is required: live verification saw Apple's advisory briefly return
+  `true` once after a successful share before settling to `false`, so
+  `should_offer` alone is not a durable idempotency key across restarts.
+  FakeGateway models the settled state and skips its second call. On
+  2026-07-14 the host returned `requested:true` for the disposable test group
+  and the receiving iPhone displayed Mapi's new contact info, closing the
+  receiver-side verification gap.
+
+**Host-verification ledger.** Exercised through `ImsgGateway` on the host Mac
+2026-07-14 (`scripts/tier2-smoke.ts`, chat 3996):
+
+- **`sendRich` subject** — live-verified: `chat.db message.subject` populated,
+  and the bold subject line rendered receiver-visible on the test phone.
+- **`sendPoll`** — live-verified: renders as a native interactive poll on the
+  receiving device; `poll.send` returns the balloon guid as `guid` (the earlier
+  `messageGuid` read was wrong and is fixed), confirmed via poll readback.
+- **`sendRichLink`** — live-verified delivered after the Mapier fork fixed the
+  bridge's deferred `dispatch_after` path (`mapier/richlink-sync-fix`). The host
+  recorded an `is_sent=1` URLBalloonProvider row and `send_status` reported
+  delivery. The RPC still returns only `{ok, queued}` with no guid, so that
+  immediate response alone is not delivery proof.
+- **`sendAttachment`** — `send.attachment` returns a guid synchronously;
+  attachment-join row (and `is_audio_message=1` for the `audio:true` leg)
+  verified via a direct `chat.db` read. Opt-in via `--attachment`/`--audio-file`.
+
+Each leg prints an EYEBALL step because a local write is not proof of
+receiver-visible delivery (the group-photo lesson). The `sendRich`
+text/effect/reply path was already live-verified.
+
+- **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
+  `ImsgWatch` (`src/imsg/watch.ts`) owns a dedicated `ImsgRpc.subscribe` process wrapping
+  `watch.subscribe` with `include_reactions:true` and `attachments:true`. When the caller
+  supplies a durable cursor, the SDK retires that read-side process every 10 seconds and
+  resumes a fresh process from the last observed global rowid. The overlap-free handoff is
+  lossless because the cursor is exclusive, and duplicate replay at the boundary is discarded.
+  The rotation timer starts when the process is created; it does not wait for the native
+  `watch.subscribe` acknowledgement, which can itself remain pending. This bounds a native
+  subscription that remains process-alive but silently stops reading `chat.db`; transport
+  heartbeat alone is not delivery health. The paired native watcher gives an unjoined row a
+  bounded two-second window to acquire its chat association, then skips it so that malformed
+  row cannot hold the global cursor behind the SDK's ten-second supervision deadline. The RPC
+  emits a content-free `watch.warning`, which the SDK reports as
+  `imsg_watch_unresolved_chat_row_skipped`, whenever that recovery path is used, and advances the
+  rotating cursor through that row so a tail orphan is not retried forever. A cursorless
+  subscription keeps its first native session until its first event establishes a resumable rowid.
+  **Single consumer.** The event queue is instance-shared; a second concurrent subscriber
+  would silently steal events, so both implementations throw on one. Documented divergence:
+  ImsgGateway allows one `subscribe()` per gateway *lifetime* (the SDK rotates its internal
+  read process; callers still do not re-subscribe), while FakeGateway allows
+  *sequential* re-subscription (one active at a time) so the simulator can model
+  reconnect-after-downtime against a single in-memory store.
+
+- **listChats(limit?)** — read-only portable chat directory for backfill. Rows
+  carry the local execution-only `chatId`, portable conversation GUID, group bit,
+  canonical participants, and last-message timestamp. A full page means the caller has
+  not proved directory completeness. Rows missing portable GUID or participants are
+  omitted and therefore also prevent a completeness claim.
+- **historyRange(chatId, range)** — oldest-first, reaction-row-free messages within an
+  inclusive `startAt` and exclusive `endBefore` time window. It optionally includes
+  attachment metadata. A backfill consumer recursively splits a full window rather than
+  treating a bounded response as complete; a still-full minimum window becomes a
+  disclosed backfill gap.
+
+**Lifecycle.** Every JSON-RPC request has a 30-second monotonic owner timeout. A timeout
+rejects the request, retires the whole RPC child, and invokes the unexpected-exit callback;
+the owner must fail closed because any in-flight mutation may already have started. This also
+bounds a native RPC process that remains alive before accepting its first request (including a
+headless macOS permission wait). Spawn failures follow the same callback path instead of
+escaping as an unhandled child-process error.
+
+The Gateway contract has no abort or close signal: quiescing a consumer does
+not promise that an outstanding `AsyncIterator.next()` inside `ImsgGateway.subscribe()` was
+canceled. The process owner stops the Gateway during final shutdown. An intentional
+`ImsgRpc.stop()` closes the child without invoking its unexpected-exit callback; an exit
+that occurs before an intentional stop still invokes that callback so the process owner can
+fail closed (covered by `tests/imsg-rpc.test.ts`).
+
+- **history(chatId, limit)** — most recent `limit` messages in a chat, both sides, reactions
+  and attachment metadata included. `ImsgRpc.history` (`src/imsg/rpc.ts`)
+  calls `messages.history` with `attachments:true` and re-sorts
+  oldest-first by `id` because RPC order is undocumented — any Gateway impl must return the
+  same normalized order.
+- **send(target, text)** — one outbound text. `target` is `{ chatId }` for an existing thread
+  (DM or group) or `{ to: handle }` for a DM by handle, find-or-creating the thread. Returns
+  `{ ok, id?, guid? }`; `ok: false` on failure — see §2 failure modes.
+- **react(chatId, reaction, expectedGuid?)** — send a tapback to the chat's most-recent
+  **incoming** bubble (the real CLI's own semantics — our outbound messages are never the
+  target); there is no message-id targeting because the real path doesn't have one (§2).
+  `expectedGuid` is a **precondition, not targeting**: if provided and the newest incoming
+  bubble is no longer that guid at fire time, the react is skipped
+  (`{ ok: true, skipped: 'stale-target' }`) — a queued react must not tag a message that
+  arrived after the decision was made. Implementations also skip
+  (`skipped: 'already-reacted'`) when the same reaction from us is already active on the
+  target — our own `react()` never un-reacts (toggle protection; see §2). `ok: false` means
+  the reaction did not verifiably land (§2 "exit 0 lies").
+- **createGroup(handles, firstMessage)** — create a group thread and send its first message
+  in one call through the native `chats.create` IMCore bridge. An older native binary that
+  conclusively returns JSON-RPC `method not found` uses the guarded GUI compose fallback.
+  Returns the new `chatId`, located by **content**: the thread whose recent history contains
+  our `firstMessage`, not merely one matching the participant set (§2). Throws if the message
+  never appears — the compose can fail silently. No standalone "create empty group" or
+  "add participant" exists.
+- **recentReactions(chatId, limit?)** — user tapbacks on OUR messages, newest-first; `limit`
+  bounds the returned notes (~10 default). Read from history's per-message `reactions[]`
+  aggregates (§2), so it survives process restarts. **Scan ceiling:** only the chat's most
+  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.
+- **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
+  keeps an in-memory `handle → chat_id` cache warmed by inbound traffic; this recovers it on a
+  cold miss — a link completion replaying after a pod restart, before the user's next message,
+  would otherwise defer forever (imsg-agent's `handleLinkCompletion`). The real path derives
+  the DM row as the non-group chat whose sole `participants[]` entry is the handle (live-verified
+  2026-07-08 against imsg 0.12.3, `scripts/chats-probe.ts`: 37/37 DM rows carried exactly one
+  participant = the peer handle; DM-vs-group is `!is_group`, never participant count). The method
+  itself passed its host-Mac smoke the same day — `scripts/resolve-dm-smoke.ts` (the manual rule-1
+  gate for this method; re-run it on imsg upgrades): known test-phone handle → its exact chat_id,
+  unknown handle → null with no thread composed, repeat resolve stable.
+- **resolveGroupChat(request)** — read-only portable group resolution. It makes one high-ceiling
+  local `chats.list` read and uses each group row's portable `guid` and `participants` directly;
+  it does not open every group's message history. It accepts a result only when the
+  scan is complete, exactly one row has the requested GUID, and its normalized participant set
+  exactly equals `expectedParticipantExternalIds` after removing the explicitly declared pod/self
+  identities. Invalid input, an incomplete directory, no match, duplicate matches, an unreported
+  membership, and membership drift are distinct fail-closed outcomes. `guid` and `participants`
+  are optional on the imsg wire, so a group row without `guid` makes the directory incomplete;
+  an otherwise readable matching group without `participants` yields
+  `participant_directory_unavailable`, never `participant_mismatch`: reporting drift
+  about members that were never read would silently disable matching against a correct ops chat,
+  which is the exact "`imsg` lies" failure class this contract exists to catch. `FakeGateway` can
+  reach both degraded states through `setGroupDirectoryComplete` and
+  `setGroupParticipantsUnreported`, so neither branch is fake-unreachable. Live verification on
+  2026-07-14 against imsg 0.12.3 read all 3,922 visible chats in about one second; all 96 group rows
+  reported a GUID and participants, and `scripts/resolve-group-smoke.ts` passed exact resolution,
+  stable repeat resolution, membership mismatch, and unknown-GUID rejection. That live run is
+  the verification of record; no separate evidence row exists. The returned numeric `chat_id` is an ephemeral
+  process-local execution target: it is never configuration, durable state, or connector payload.
+  `scripts/resolve-group-smoke.ts` is the read-only host-Mac rule-1 gate.
+- **sendStatus(guid)** — read-only `message.send_status` lookup in chat.db; it
+  does not require the bridge. Missing rows normalize to `pending` with null
+  status fields. Recipient read-receipt settings legitimately leave
+  `date_read`/`date_delivered` null for many users; normalized delivery state is
+  reliable regardless. FakeGateway reports `sent` only for guids it emitted and
+  never invents delivered/read evidence; unknown guids are `pending` with null fields.
+  **Host-verified 2026-07-14:** a freshly-sent guid returned
+  `send_state:"delivered"` with `is_sent/is_delivered:true`, `date_delivered`
+  populated, and `date_read:null` (recipient read-receipts off) — the exact
+  `status_fields` shape the wrapper types model.
+
+## 2. Behavioral invariants FakeGateway must reproduce
+
+This is the heart of the doc. Every item here is either load-bearing for agent logic today or
+a hard ceiling on what iMessage can do — FakeGateway gets both right or it isn't a fake, it's
+a different product.
+
+- **Monotonic ids, global, never reused.** `id` mirrors `chat.db` rowid semantics: it strictly
+  increases across **all** chats, not per-chat. The cursor protocol (`id > cursor`, exclusive)
+  in imsg-agent (`handleInbound`) depends on this — `if (msg.id <= (await store.getCursor())) return;`. A
+  FakeGateway that resets ids per chat, or reuses one, breaks cursor advance silently.
+
+- **Echo of own sends.** A successful `send()` later arrives back through the event stream
+  as a message with `is_from_me: true`, and shows up in `history()`. Cursor advance, history
+  hydration (imsg-agent's `toModelMessages`), and same-role message merging all
+  assume this echo happens. FakeGateway must emit it, not just record the send silently.
+
+- **history() hides reaction ROWS but carries reaction STATE.** Verified live on imsg 0.12.0
+  (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.
+  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
+  that just booted has seen no stream events yet.
+  Caveat: in `reactions[]`, trust `is_from_me`, not `sender` — the live binary fills `sender`
+  with the chat peer's handle even for our own reactions.
+  FakeGateway must reproduce both halves: filter reaction rows out of `history()` AND maintain
+  `reactions[]` on each message.
+  Text can be present in FakeGateway even where the real store's raw `text` column would be
+  `NULL` (real iMessage decodes `attributedBody` — see `docs/host-mac-control.md` §4).
+  FakeGateway just stores text plainly; only the outward guarantee that `text` is populated
+  matters.
+
+- **Message event shape** (`ImsgMessage`, `src/types.ts`):
+  `id, chat_id, is_group, guid, sender, sender_name, is_from_me, text, created_at,
+  reactions[]`.
+  Reaction events additionally carry:
+  `is_reaction, reaction_type, reaction_emoji, is_reaction_add, reacted_to_guid`.
+  Fake↔live reaction-event shape verified against the 2026-07-03 live capture.
+  FakeGateway events must be structurally identical — same fields, same optionality.
+  When attachment metadata was requested, a message may additionally carry
+  `attachments[]`: `filename` plus optional `transfer_name`, `uti`, `mime_type`,
+  `total_bytes`, `is_sticker`, `missing`, and local absolute `original_path`.
+  Field names are the LIVE RPC wire shape (host-verified 2026-07-14 via
+  `messages.history attachments:true` against the injected 0.13.0 build) — the
+  fork's `docs/attachments.md` table lists `byte_size`/`path`, but the binary
+  emits `total_bytes`/`original_path`; the wire wins. The file is already on
+  the host Mac; no download verb exists. `missing:true` means Messages aged the
+  local file out. The fork omits `attachments` when none exist, and FakeGateway
+  does the same. **Host-verified 2026-07-14:** a `send-attachment` PNG and a
+  prior voice-note `.aiff` both read back through history with the full field
+  set populated.
+  Host paths are execution details and never cross a remoting wire.
+
+- **`chat_guid` is populated on every message and history row** (live-verified 2026-07-02
+  against imsg 0.12.0 and re-verified 2026-07-07 against imsg 0.12.3): DMs are
+  `any;-;<handle>` (e.g. `any;-;+17738867338`), groups are
+  `any;+;<32-hex>`. It is the stable, portable thread identifier — `chat_id` is a local
+  chat.db ROWID and must never be persisted off-Mac (the Supabase store keys
+  `agent_message_log`/`agent_turns` on `chat_guid`, v0/design.md §4). FakeGateway synthesizes
+  the same formats per chat.
+
+- **Portable group resolution never trusts a saved numeric rowid.** `chat_id` can change across
+  Mac state and never identifies a portable thread. Both gateways therefore resolve a group GUID
+  afresh, require a complete unique directory result, and compare exact normalized membership
+  independently from the set of handles authorized to act. A partial scan or participant mismatch
+  disables the dependent workflow; it never falls back to a saved numeric chat id.
+
+- **A DM's chat_id is recoverable from the handle at any time, but only if the thread exists.**
+  `chats.list` (`src/imsg/rpc.ts`) is authoritative and restart-safe: the real gateway can map a
+  handle back to its `chat_id` whenever a DM thread is present, because chat.db persists the
+  peer handle as the row's sole `participants[]` entry (live-verified — see §1 `resolveDmChat`).
+  It cannot conjure a chat_id for a handle that has never messaged (no row exists yet). This is
+  why the runtime's cold-cache recovery is a *resolve-or-defer*, never a create: `resolveDmChat`
+  returns the id if the thread exists and `null` otherwise, and the completion stays unprocessed
+  (store-redelivered) until inbound traffic actually creates the DM. FakeGateway mirrors both
+  halves — its `resolveDmChat` finds an existing DM chat and returns `null` for an unknown handle,
+  never minting one (that would let the sim deliver where the real gateway defers).
+
+- **Reactions toggle — and our own react() must therefore guard.** On the platform, reacting
+  with a type that already exists from the same sender on the target bubble **removes** it
+  (event with `is_reaction_add: false`) — it does not no-op or stack. Tapbacks are per-sender:
+  we can only ever toggle OUR OWN reactions; another party's tapback is untouchable. FakeGateway
+  must model toggle for *other parties* (fixture driver `injectReaction` simulates a user's
+  tapback, toggling on repeat). But the Gateway's own `react()` never un-reacts: it checks the
+  target's `reactions[]` in history and skips with `{ skipped: 'already-reacted' }` instead of
+  firing a removal (live incident 2026-07-01: an unguarded react removed an agent-account heart
+  placed manually on the host Mac). Toggle is platform truth; the guard is our contract on top
+  of it.
+
+- **react() targets the most-recent INCOMING bubble in the chat, full stop.** The real path
+  (`src/imsg/react.ts`, `imsg react --chat-id <id> --reaction <r>`) takes no message id, and
+  per its own help text reacts to "the most recent incoming message" — our own outbound
+  bubbles are never the target. FakeGateway's `react()` signature must not accept a message id
+  either, and must apply the reaction to the chat's newest incoming message only. Building a
+  "react to message N" feature against a fake that supports arbitrary targeting produces a
+  feature the real gateway cannot deliver.
+  Reaction set is closed: exactly the 6 tapback types in `REACTIONS`
+  (`src/imsg/react.ts`) — `love, like, dislike, laugh, emphasis, question`. No arbitrary-emoji
+  sending.
+  **DM-only.** The real automation (`scripts/react.applescript`, ours — `imsg react` was
+  dropped for firing into the focused chat when its search-select race loses) verifies the
+  focused thread by comparing handle digits against the window title, which group titles
+  don't carry. `react()` on a group chat returns `{ ok: false }` on both implementations.
+
+- **react() exit 0 lies — success must be verified.** Observed live (2026-07-02): one
+  `imsg react` run exited 0 having applied nothing anywhere; another applied the tapback in
+  the WRONG chat (the UI automation acts on whatever chat Messages.app has focused when chat
+  selection fails). ImsgGateway therefore polls the target chat's history after firing and
+  reports `ok: true` only once the reaction appears on the intended message's `reactions[]`;
+  otherwise `ok: false`. Callers must treat `ok: false` as "did not happen" — never assume a
+  fired react landed. This is also why the 20× react precision gate (issue #13) exists.
+  **Cmd+T can silently fail — and the fallout is a SENT TEXT, not a no-op.** Observed live
+  (2026-07-17, display asleep on the host): the tapback picker never opened, the reaction key
+  landed in the compose field, and the script's trailing Return sent a literal `"1"` to the
+  chat. `react.applescript` therefore guards after typing the reaction key: if the focused UI
+  element is a text input containing the key, it clears the field and aborts with an error
+  (surfacing as `{ ok: false }`) instead of pressing Return. A failed react must never mutate
+  the conversation.
+
+- **Group semantics.**
+  - `is_group: true`, chat identified by a hex-string identifier for groups (per
+    `docs/host-mac-control.md` §4: "numeric chat_id per thread; hex identifier = group chat").
+  - Messages carry `participants[]` in group chats.
+  - Groups are created **only** via `createGroup` — sending the first message is what creates
+    the thread. The real path is the native `chats.create` IMCore bridge; guarded `Cmd+N`
+    compose automation is only a compatibility fallback for binaries without that RPC method.
+    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`.
+  - **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
+    thread. `create-group.applescript` verifies the window title changed after Cmd+N (chat
+    title → "Messages") and aborts before typing anything if it didn't.
+  - **Group create can fail silently** (observed live 2026-07-02: recipient flapped from
+    iMessage to SMS registration; compose exited 0, no thread created, no message sent —
+    SMS handles cannot join an iMessage group). And Messages may **reuse an existing thread**
+    with the same participant set instead of creating a new one. Both are why the new thread
+    is located by content (recent history contains `firstMessage`) with a timeout that throws,
+    never by participant-set match alone.
+  - DMs are keyed by handle: `send({ to: handle }, text)` finds-or-creates the DM thread.
+
+- **Latency & ordering are not instant.** Real sends take ~1–3s (AppleScript round trip);
+  real events arrive with debounce (~500ms) and can batch after a downtime gap (catch-up from
+  cursor on reconnect). FakeGateway should support a configurable artificial latency and a
+  catch-up/backlog mode so mailbox debounce and per-chat serialization
+  (imsg-agent's `Mailbox`) get exercised the way they will in production, not just against
+  an instant no-op fake.
+
+- **Failure modes to simulate**, all of which the agent must survive without corrupting state:
+  - send failure (network/imsg error) — `send()` resolves `{ ok: false }` or rejects.
+  - react failure (UI-automation flake, nonzero exit from `imsg react`).
+  - gateway process death mid-stream — on reconnect, the agent must resume from its stored
+    cursor without re-processing or double-replying to anything at or before that cursor
+    (imsg-agent's `handleInbound` + stored cursor).
+
+- **Native poll readback (imsg 0.12.3, live-verified 2026-07-07, full capture
+  in `docs/imsg-polls.md`).** Poll activity arrives as regular message rows with a `poll`
+  payload (`MessagePoll`, `src/types.ts`) on BOTH subscribe and history — unlike reaction
+  rows, history does NOT hide them, so poll state is restart-safe. Three row shapes:
+  - **Creation is TWO rows**: a balloon row (`poll.kind: "created"`,
+    `metadata.associated_message_type` 3 — observed 0 transiently right after send, Messages
+    restamps it, so classification must never key on the balloon's value — question +
+    options, imsg-synthesized display text
+    `"Sent a poll"`) followed by a plain caption row carrying the question with
+    `reply_to_guid` = the balloon guid — Messages never renders the poll title on the
+    balloon, so imsg always sends the caption.
+  - **A vote is a NEW row** (`metadata.associated_message_type` 4000, `poll.kind: "vote"`):
+    `poll.votes[]` is that participant's CURRENT selections (state, not an event log — a
+    re-vote is a new row with the new full selection), `option_text` pre-resolved by imsg,
+    `original_guid` = the balloon guid. Display text is a junk single space.
+  - **An added option ("Add Choice") is a NEW row** (`metadata.associated_message_type` 2)
+    re-carrying the FULL updated option list — but imsg mislabels it `poll.kind: "created"`
+    and its `poll.question` is unreliable. Display text is a junk U+FFFD. Consumers must
+    classify rows via `pollEventKind` and resolve the question through `original_guid` → the
+    balloon row (`src/polls.ts`) — never trust `kind`/`question` on non-balloon rows.
+  The Gateway creates polls through `sendPoll`; the manual host-Mac CLI equivalent is
+  `imsg poll send` (bridge-injected — `docs/imsg-polls.md`). FakeGateway reuses
+  `injectPollCreate` for the same balloon+caption postcondition. Vote and option-update
+  fixture drivers (`injectPollVote` / `injectPollAddOption`) reproduce the remaining shapes
+  above including the junk display texts and the kind mislabel; there is still no Gateway
+  poll vote/unvote surface. Open/unverified: the wire shape of a bare vote retraction (the
+  fake refuses empty selections until it's observed live) and multi-option selections.
+
+- **Forbidden surface — none of this exists on the real path, so FakeGateway must not offer
+  it:**
+  - voting or unvoting on native polls through the Gateway (`sendPoll` creates polls only)
+  - sending an arbitrary/custom-emoji tapback through stock `tapback` — that
+    verb deliberately stays on the closed 6-type `Reaction` set. The separate
+    `emojiTapback` verb exists only when the patched bridge advertises its
+    capability marker
+  - outbound threaded replies through plain `send()` — inline replies exist only via
+    `sendRich`'s `replyToGuid` (Tier 2); `send()` has no reply parameter
+
+  Moved out of this list once Tier 2 landed (see "Tier 2" above for what each one actually
+  does and does not add): typing indicators, read receipts, editing/unsending/deleting
+  messages, reacting to an arbitrary (non-most-recent) message, and participant management
+  on an existing group (add/remove/rename/photo/leave).
+
+- **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
+  (imsg-agent's `toModelMessages`, `if (!m.text) continue;`), and that "gracefully" needs a fixture to
+  keep being true.
+
+## 3. FakeGateway initial design
+
+- **Backing store**: `sim_messages` table (Supabase local/dev) or in-memory for unit tests.
+  Auto-increment `id` is the rowid analog and must satisfy the global-monotonic invariant in
+  §2. `sim_chats` holds `is_group` / `participants`. Reactions are stored as message-shaped
+  rows with an association back to the target (mirroring `chat.db`'s
+  `associated_message_type` / `associated_message_guid` shape described in
+  `docs/host-mac-control.md` §4), not as a separate table — but `history()` must **filter
+  them out** while maintaining each message's `reactions[]` aggregate, mirroring the real
+  path (§2); reaction ROWS reach the agent only through the subscribe stream, reaction STATE
+  through history.
+- **Drivers**:
+  1. Programmatic API for eval fixtures — inject an inbound message, reaction, or poll
+     event (`injectInbound` / `injectReaction` / `injectPollCreate` / `injectPollVote` /
+     `injectPollAddOption`), assert on outbound sends/reacts.
+  2. The simulator web UI (multi-fake-user iMessage-style chat) reads/writes the same store,
+     so a human can drive the same fixtures the eval harness does.
+- **Determinism knobs**: `latency: 0` + no debounce batching for unit tests (fast, deterministic);
+  realistic timings for integration runs that need to exercise the mailbox debounce/serialize
+  path for real.
+- **Hosted-Dev persistence**: `snapshot()` returns a versioned
+  `FakeGatewaySnapshot`; `devRestoreSnapshot()` accepts that exact contract.
+  The snapshot includes chats and current group names, messages, sent GUIDs,
+  reachable-address evidence, Name & Photo sharing state, and the degraded
+  group-directory fixture state. Restoring it must preserve `sendStatus()`,
+  `checkHandle()`, Name & Photo idempotency, current group metadata, and both
+  global monotonic counters. This driver-only API is not a `Gateway`
+  capability and has no real-gateway counterpart.
+
+## 4. Conformance test suite
+
+One spec file, parameterized by `Gateway` implementation, using the existing `node:test`
+harness (`tsx --test`, see `package.json`). Required cases:
+
+- cursor monotonicity (global, exclusive, never reused)
+- send echo (own send reappears via subscribe + history with `is_from_me: true`)
+- history returns both sides, **hides reaction rows**, and carries `reactions[]` aggregates
+- reaction toggle round-trip via the fixture driver (`injectReaction` → event
+  `is_reaction_add: true` → inject same again → `is_reaction_add: false`)
+- own `react()` toggle-guard: second `react()` of the same type returns
+  `{ skipped: 'already-reacted' }`, no removal event
+- stale-target skip: `react(chat, r, expectedGuid)` after a newer incoming message arrived
+  returns `{ skipped: 'stale-target' }`, no reaction applied
+- react targets the most-recent INCOMING message only — our own newer outbound does not
+  change the target
+- recentReactions surfaces user tapbacks on our messages only, newest-first
+- group create → send-by-chat-id works immediately after
+- catch-up after simulated downtime (events since cursor arrive, nothing before it re-fires)
+- poll create lands as a balloon row with `poll` payload plus a plain caption row, both
+  visible in history (poll rows are never hidden)
+- a vote arrives as a NEW row carrying the voter's current selections with resolved
+  `option_text`; a re-vote is another new row with the new full selection
+- a user-added option re-carries the full option list, mislabeled `kind:"created"` with
+  `metadata.associated_message_type` 2 and junk display text
+- poll fixtures refuse unverified real-path behavior (unknown option ids, empty selections)
+- send failure surfaces as `{ ok: false }` (or rejection) without corrupting cursor state
+- `resolveDmChat(handle)` returns an existing DM's `chat_id`, `null` for a handle with no
+  thread, and creates nothing on the miss (read-only — mirrors the real path reading chat.db)
+- portable group resolution accepts only a complete unique GUID hit with exact normalized
+  membership; missing GUID and participant drift fail closed without creating a thread
+- attachment metadata round-trips intact through history and subscribe; plain
+  messages omit `attachments`
+- `sendStatus` returns pending/null fields for an unknown guid and sent-or-better
+  for guids emitted by `send`/`sendRich`, without inventing delivery/read evidence
+- `checkHandle` reports known phone/email chat participants reachable, conservatively
+  reports a well-formed unknown unavailable, and rejects malformed input
+- `tapback` targets an explicit message guid (older than the newest incoming), not just the
+  newest incoming; add/remove are explicit (repeat add skips `already-reacted`, remove of an
+  inactive reaction skips `not-reacted`, never a toggle); works in a group chat; `ok: false`
+  for an unknown message guid
+- `emojiTapback` sends a custom emoji to an explicit guid, carries
+  `type:"custom"` + the exact emoji in history, and uses the same explicit
+  add/remove skip semantics; disabling its capability makes it return
+  `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
+- `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
+  write-only through `ImsgMessage`)
+- `sendAttachment` and its `audio:true` mode echo an outbound row, preserve an optional
+  inline-reply guid, and return `ok:false` for an unknown chat; the synchronous
+  send response does not prove attachment/audio readback metadata
+- `sendSticker` echoes an outbound row and guid for a known chat, returns
+  `ok:false` for an unknown chat, and fails closed when `stickerSend` is absent
+- `sendPoll` emits the native balloon+caption two-row shape, returns the balloon guid, and
+  returns `ok:false` for fewer than two options or an unknown chat
+- `sendRichLink` echoes an outbound row and returns `ok:false` for an unknown chat; preview
+  metadata is not queryable through `ImsgMessage`
+- `editMessage` changes the target row's text in place — same row count before/after, no
+  new row
+- `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
+- `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
+- `setGroupPhoto`/`leaveGroup` return `ok: true` against a group and `ok: false` against a DM
+- patched sticker, group-photo, and participant verbs return `ok:false` without mutation
+  when their `imsg status` capability markers are absent
+- `recentReactions` surfaces an inbound custom-emoji reaction (`reaction: 'custom'`) with the
+  real `emoji` intact
+- Fake-only restart coverage snapshots and restores a world, then proves
+  `sendStatus`, `checkHandle`, Name & Photo idempotency, current group metadata,
+  fixture state, and monotonic IDs survive exactly
+
+FakeGateway runs this suite in CI on every PR. ImsgGateway runs it as a manual runbook step on
+the host Mac (see `docs/host-mac-control.md`) until a host-Mac CI runner exists — at that point
+it becomes CI-optional, not CI-required, since it depends on physical-Mac state (unlocked
+session, TCC grants, an idle test phone).
+
+**Rule for contributors**: any new capability added to FakeGateway requires, in the same PR:
+
+1. Proof the real path supports it — a manual test run against ImsgGateway on the host Mac,
+   pasted into the PR description.
+2. A conformance test added to this suite, passing against both implementations.
+3. An update to this doc (§1 interface and/or §2 invariants).
+
+Skip any of the three and the capability is forbidden surface, full stop — delete it rather
+than merge it half-specified.