@mapier/imsg-sdk 0.1.0

package/dist/gateway/fake.js

@@ -0,0 +1,870 @@
+import { aggregatePolls } from '../polls.js';
+import { PATCHED_GATEWAY_CAPABILITIES, toReactionNoteType } from './types.js';
+import { classifyGroupChatResolution } from './portable-chat.js';
+// How far back recentReactions() scans, mirroring ImsgGateway's
+// history(chatId, 30) read — keep the two in lockstep (contract §2).
+const HISTORY_SCAN_WINDOW = 30;
+const REACTION_EMOJI_BY_TYPE = {
+    love: '❤️',
+    like: '👍',
+    dislike: '👎',
+    laugh: '😂',
+    emphasis: '‼️',
+    question: '❓',
+};
+// Only "Liked" is live-verified; the other verbs are extrapolated and the text
+// is display-only, never parsed — runtime.ts branches on is_reaction before
+// text is ever read.
+const REACTION_ADD_VERB_BY_TYPE = {
+    love: 'Loved',
+    like: 'Liked',
+    dislike: 'Disliked',
+    laugh: 'Laughed at',
+    emphasis: 'Emphasized',
+    question: 'Questioned',
+};
+function reactionEventText(type, emoji, isAdd, targetText) {
+    const quotedTarget = `"${targetText ?? ''}"`;
+    if (type === 'custom') {
+        // Custom emoji-picker summary copy is extrapolated and display-only; never
+        // parsed by runtime.ts because is_reaction is handled first.
+        return isAdd ? `Reacted ${emoji} to ${quotedTarget}` : `Removed ${emoji} from ${quotedTarget}`;
+    }
+    if (isAdd) {
+        return `${REACTION_ADD_VERB_BY_TYPE[type]} ${quotedTarget}`;
+    }
+    // Removal summary copy is extrapolated and display-only; never parsed by
+    // runtime.ts because is_reaction is handled first.
+    return `Removed a ${type} from ${quotedTarget}`;
+}
+// In-memory Gateway for unit tests and the simulator. No DB, no imsg binary.
+// Must reproduce every invariant in docs/gateway-contract.md §2 exactly —
+// see that doc before changing behavior here.
+export class FakeGateway {
+    capabilities;
+    messages = [];
+    chats = new Map();
+    // Group-directory fidelity knobs. Default to the healthy real-gateway shape;
+    // the drivers below reach the degraded states ImsgGateway can actually report.
+    groupDirectoryComplete = true;
+    groupParticipantsUnreported = new Set();
+    namePhotoSharedChats = new Set();
+    reachableAddresses = new Set();
+    sentGuids = new Set();
+    nextId = 1;
+    nextChatId = 1;
+    latencyMs;
+    subscribers = new Set();
+    activeSubscribers = 0;
+    forcedSendFailure = false;
+    constructor(opts = {}) {
+        this.latencyMs = opts.latencyMs ?? 0;
+        this.capabilities = { ...PATCHED_GATEWAY_CAPABILITIES, ...opts.capabilities };
+    }
+    async delay() {
+        if (this.latencyMs > 0)
+            await new Promise((r) => setTimeout(r, this.latencyMs));
+    }
+    allocId() {
+        return this.nextId++;
+    }
+    emit(msg) {
+        this.messages.push(msg);
+        if (msg.is_from_me && !msg.is_reaction)
+            this.sentGuids.add(msg.guid);
+        for (const sub of this.subscribers)
+            sub(msg);
+    }
+    ensureDmChat(handle) {
+        for (const chat of this.chats.values()) {
+            if (!chat.isGroup && chat.participants[0] === handle)
+                return chat;
+        }
+        const chat = {
+            chatId: this.nextChatId++,
+            guid: `any;-;${handle}`,
+            isGroup: false,
+            participants: [handle],
+        };
+        this.chats.set(chat.chatId, chat);
+        this.reachableAddresses.add(handle);
+        return chat;
+    }
+    latestMessage(chatId) {
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const m = this.messages[i];
+            if (m && m.chat_id === chatId && !m.is_reaction)
+                return m;
+        }
+        return undefined;
+    }
+    // Mirrors the real react path: the CLI targets the most recent INCOMING
+    // message (imsg 0.12.0 help text) — our own bubbles are never the target.
+    newestIncoming(chatId) {
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const m = this.messages[i];
+            if (m && m.chat_id === chatId && !m.is_reaction && !m.is_from_me)
+                return m;
+        }
+        return undefined;
+    }
+    // Base message-row envelope (contract §2 "Message event shape") — the one
+    // place to grow the shape. Everything but reaction rows builds on this;
+    // fields overrides/extends the defaults.
+    buildMessage(chat, fields) {
+        const id = this.allocId();
+        return {
+            id,
+            chat_id: chat.chatId,
+            chat_guid: chat.guid,
+            chat_name: chat.isGroup ? chat.name : undefined,
+            is_group: chat.isGroup,
+            guid: `fake-msg-${id}`,
+            reactions: [],
+            participants: chat.isGroup ? chat.participants : undefined,
+            created_at: new Date().toISOString(),
+            ...fields,
+        };
+    }
+    buildOutboundMessage(chat, text) {
+        return this.buildMessage(chat, { is_from_me: true, text });
+    }
+    // Toggle bookkeeping shared by react() (actor = us) and injectReaction
+    // (actor = the other party's handle) — same primitive, different caller.
+    // Maintains the target message's reactions[] aggregate (the state the real
+    // gateway reads from history) and emits the reaction event (the row the
+    // real gateway sees on the watch stream).
+    toggleReaction(chatId, targetGuid, isFromMe, senderHandle, senderName, type, emoji) {
+        const target = this.messages.find((m) => m.guid === targetGuid);
+        if (!target)
+            throw new Error(`toggleReaction: no message with guid ${targetGuid}`);
+        target.reactions ??= [];
+        const existingIdx = target.reactions.findIndex((r) => r.type === type && r.emoji === emoji && r.is_from_me === isFromMe && (isFromMe || r.sender === senderHandle));
+        const nowActive = existingIdx === -1;
+        const id = this.allocId();
+        const createdAt = new Date().toISOString();
+        if (nowActive) {
+            const entry = {
+                id,
+                type,
+                emoji,
+                is_from_me: isFromMe,
+                sender: senderHandle,
+                created_at: createdAt,
+            };
+            target.reactions.push(entry);
+        }
+        else {
+            target.reactions.splice(existingIdx, 1);
+        }
+        const msg = {
+            id,
+            chat_id: chatId,
+            chat_guid: this.chats.get(chatId)?.guid,
+            is_group: this.chats.get(chatId)?.isGroup ?? false,
+            guid: `fake-reaction-${id}`,
+            sender: senderHandle,
+            sender_name: senderName,
+            is_from_me: isFromMe,
+            text: reactionEventText(type, emoji, nowActive, target.text),
+            reactions: [],
+            is_reaction: true,
+            reaction_type: type,
+            reaction_emoji: emoji,
+            is_reaction_add: nowActive,
+            reacted_to_guid: targetGuid,
+            created_at: createdAt,
+        };
+        this.emit(msg);
+        return msg;
+    }
+    // ---- Gateway interface ----
+    async *subscribe(sinceId = 0) {
+        // Single ACTIVE consumer, mirroring the real path (contract §1) — the
+        // real gateway's event queue is instance-shared and refuses a second
+        // subscriber, so the fake must not offer concurrent subscriptions either.
+        // Sequential re-subscription (subscribe → break → subscribe) stays legal:
+        // it models reconnect-after-downtime.
+        if (this.activeSubscribers > 0) {
+            throw new Error('FakeGateway.subscribe: already subscribed — one active consumer per gateway');
+        }
+        this.activeSubscribers++;
+        const queue = [];
+        let wake = null;
+        let lastDelivered = sinceId;
+        const handler = (msg) => {
+            if (msg.id > lastDelivered) {
+                queue.push(msg);
+                wake?.();
+            }
+        };
+        try {
+            // Catch-up: replay anything already stored beyond the cursor before
+            // going live — mirrors reconnect-after-downtime (contract §2).
+            for (const m of this.messages) {
+                if (m.id > lastDelivered) {
+                    lastDelivered = m.id;
+                    yield m;
+                }
+            }
+            this.subscribers.add(handler);
+            for (;;) {
+                const next = queue.shift();
+                if (next) {
+                    lastDelivered = next.id;
+                    yield next;
+                }
+                else {
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                    });
+                    wake = null;
+                }
+            }
+        }
+        finally {
+            this.subscribers.delete(handler);
+            this.activeSubscribers--;
+        }
+    }
+    async history(chatId, limit = 30) {
+        await this.delay();
+        // Mirrors the real path: history hides reaction ROWS but each message
+        // carries its current reactions[] aggregate (contract §2).
+        const msgs = this.messages.filter((m) => m.chat_id === chatId && !m.is_reaction);
+        return msgs.slice(-limit);
+    }
+    async listChats(limit = 10_000) {
+        await this.delay();
+        return [...this.chats.values()]
+            .map((chat) => {
+            const last = [...this.messages].reverse().find((message) => message.chat_id === chat.chatId);
+            return {
+                chatId: chat.chatId,
+                conversationExternalId: chat.guid,
+                isGroup: chat.isGroup,
+                participantExternalIds: [...chat.participants].sort(),
+                lastMessageAt: last?.created_at ?? null,
+                lastMessageId: last?.id ?? 0,
+            };
+        })
+            .sort((left, right) => right.lastMessageId - left.lastMessageId)
+            .slice(0, limit)
+            .map(({ lastMessageId: _, ...chat }) => chat);
+    }
+    async historyRange(chatId, range) {
+        await this.delay();
+        const startMs = range.startAt ? new Date(range.startAt).getTime() : null;
+        const endMs = range.endBefore ? new Date(range.endBefore).getTime() : null;
+        const messages = this.messages.filter((message) => {
+            if (message.chat_id !== chatId || message.is_reaction)
+                return false;
+            if (!message.created_at)
+                return startMs === null && endMs === null;
+            const occurredAt = new Date(message.created_at).getTime();
+            return (startMs === null || occurredAt >= startMs) && (endMs === null || occurredAt < endMs);
+        });
+        return structuredClone(messages.slice(-(range.limit ?? 500)));
+    }
+    async send(target, text) {
+        await this.delay();
+        if (this.forcedSendFailure) {
+            this.forcedSendFailure = false;
+            return { ok: false };
+        }
+        const chat = 'chatId' in target ? this.chats.get(target.chatId) : this.ensureDmChat(target.to);
+        if (!chat)
+            return { ok: false };
+        const msg = this.buildOutboundMessage(chat, text);
+        this.emit(msg);
+        return { ok: true, id: msg.id, guid: msg.guid };
+    }
+    async react(chatId, reaction, expectedGuid) {
+        await this.delay();
+        // DM-only, mirroring the real path (contract §2): group-thread titles
+        // defeat the automation's focused-chat verification.
+        if (this.chats.get(chatId)?.isGroup)
+            return { ok: false };
+        const target = this.newestIncoming(chatId);
+        if (!target || (expectedGuid !== undefined && target.guid !== expectedGuid)) {
+            return { ok: true, skipped: 'stale-target' };
+        }
+        if (target.reactions?.some((r) => r.is_from_me && r.type === reaction)) {
+            return { ok: true, skipped: 'already-reacted' };
+        }
+        this.toggleReaction(chatId, target.guid, true, undefined, undefined, reaction, REACTION_EMOJI_BY_TYPE[reaction]);
+        return { ok: true };
+    }
+    async createGroup(handles, firstMessage) {
+        await this.delay();
+        const chatId = this.nextChatId++;
+        const chat = {
+            chatId,
+            guid: `any;+;${chatId.toString(16).padStart(32, '0')}`,
+            isGroup: true,
+            participants: [...handles],
+        };
+        this.chats.set(chat.chatId, chat);
+        for (const handle of handles)
+            this.reachableAddresses.add(handle);
+        this.emit(this.buildOutboundMessage(chat, firstMessage));
+        return { chatId: chat.chatId };
+    }
+    // Inbound tapbacks on OUR messages, newest-first — read from message
+    // reactions[] state, mirroring the real gateway's history-derived path
+    // INCLUDING its ceiling: only the chat's most recent HISTORY_SCAN_WINDOW
+    // messages are scanned (the real path reads history(chatId, 30), so a
+    // tapback on an older message is invisible there — the fake must not
+    // surface what the real gateway can't; contract §2, capability rule 2).
+    async recentReactions(chatId, limit = 10) {
+        await this.delay();
+        const window = await this.history(chatId, HISTORY_SCAN_WINDOW);
+        const notes = [];
+        for (const m of window) {
+            if (!m.is_from_me || !m.reactions)
+                continue;
+            for (const r of m.reactions) {
+                if (!r.is_from_me)
+                    notes.push({ id: r.id, reaction: toReactionNoteType(r.type), emoji: r.emoji });
+            }
+        }
+        return notes.sort((a, b) => b.id - a.id).slice(0, limit);
+    }
+    // Read-only DM lookup by handle (contract: ImsgGateway reads it from
+    // chat.db). Unlike ensureDm this must NOT create — the real path returns
+    // null for a thread that doesn't exist, and FakeGateway may not exceed it.
+    async resolveDmChat(handle) {
+        await this.delay();
+        for (const chat of this.chats.values()) {
+            if (!chat.isGroup && chat.participants[0] === handle)
+                return chat.chatId;
+        }
+        return null;
+    }
+    async resolveGroupChat(request) {
+        await this.delay();
+        return classifyGroupChatResolution({
+            request,
+            // The real gateway derives this from scan-limit truncation and per-chat
+            // history readability. The fake cannot truncate, but it must still be able
+            // to REACH the state, or it silently exceeds the real gateway's guarantees
+            // and no test can cover the branch (rule 2).
+            directoryComplete: this.groupDirectoryComplete,
+            groups: [...this.chats.values()]
+                .filter((chat) => chat.isGroup)
+                .map((chat) => ({
+                chatId: chat.chatId,
+                conversationExternalId: chat.guid,
+                participantExternalIds: this.groupParticipantsUnreported.has(chat.chatId) ? null : chat.participants,
+            })),
+        });
+    }
+    async sendStatus(guid) {
+        await this.delay();
+        if (!this.sentGuids.has(guid)) {
+            return {
+                ok: true,
+                guid,
+                send_state: 'pending',
+                service: 'iMessage',
+                delivered_at: null,
+                date_read: null,
+                is_read: false,
+                status_fields: null,
+            };
+        }
+        // The fake knows it dispatched this guid, but has no recipient-side
+        // evidence for delivery or reading. Never over-claim either.
+        return {
+            ok: true,
+            guid,
+            send_state: 'sent',
+            service: 'iMessage',
+            delivered_at: null,
+            date_read: null,
+            is_read: false,
+            status_fields: {
+                is_sent: true,
+                is_delivered: false,
+                is_finished: true,
+                error: 0,
+                date_delivered: null,
+                date_read: null,
+                is_delayed: false,
+                is_prepared: false,
+                is_pending_satellite_send: false,
+                was_downgraded: false,
+            },
+        };
+    }
+    async checkHandle(address, opts) {
+        await this.delay();
+        const aliasType = opts?.aliasType ?? (address.includes('@') ? 'email' : 'phone');
+        const valid = aliasType === 'phone' ? /^\+[1-9]\d{6,14}$/.test(address) : /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(address);
+        const destination = aliasType === 'phone' ? `tel:${address}` : `mailto:${address}`;
+        if (!valid) {
+            return { ok: false, available: false, idStatus: 0, destination, service: 'iMessage', aliasType, address };
+        }
+        const available = this.reachableAddresses.has(address);
+        return {
+            ok: true,
+            available,
+            idStatus: available ? 1 : 0,
+            destination,
+            service: 'iMessage',
+            aliasType,
+            address,
+        };
+    }
+    // ---- Tier 2 (bridge-backed) methods — see gateway/types.ts and
+    // docs/gateway-contract.md §2 for what each one may and may not do. Unlike
+    // react()/createGroup(), none of these are DM-only or newest-incoming-only;
+    // they mirror the real bridge's arbitrary message/chat targeting.
+    // tapback/editMessage/unsendMessage/deleteMessage can target ANY message,
+    // but ImsgGateway locates it by scanning history(chatId, 30) BEFORE firing
+    // (contract §2 "Tier-2 guid-targeting window") — a guid older than that is
+    // invisible to the real path even though it's still in chat.db. This must
+    // return the same `undefined` the real path effectively gets in that case
+    // (parity rule 2: `this.messages` unconditionally would let the fake target
+    // a guid the real path can't reach).
+    findInScanWindow(chatId, targetGuid) {
+        return this.messages
+            .filter((m) => m.chat_id === chatId && !m.is_reaction)
+            .slice(-HISTORY_SCAN_WINDOW)
+            .find((m) => m.guid === targetGuid);
+    }
+    // Targeted tapback: any message guid (within the scan window above),
+    // explicit add/remove, works in groups. Same closed Reaction set as
+    // react(); the patched custom-emoji path is modeled separately below.
+    async tapback(chatId, targetGuid, reaction, remove = false) {
+        await this.delay();
+        const target = this.findInScanWindow(chatId, targetGuid);
+        if (!target)
+            return { ok: false };
+        const active = Boolean(target.reactions?.some((r) => r.is_from_me && r.type === reaction));
+        if (remove ? !active : active) {
+            return { ok: true, skipped: remove ? 'not-reacted' : 'already-reacted' };
+        }
+        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, reaction, REACTION_EMOJI_BY_TYPE[reaction]);
+        return { ok: true };
+    }
+    async emojiTapback(chatId, targetGuid, emoji, remove = false) {
+        await this.delay();
+        if (!this.capabilities.emojiTapback || !emoji)
+            return { ok: false };
+        const target = this.findInScanWindow(chatId, targetGuid);
+        if (!target)
+            return { ok: false };
+        const active = target.reactions?.some((r) => r.is_from_me && r.type === 'custom' && r.emoji === emoji) ?? false;
+        if (remove ? !active : active) {
+            return { ok: true, skipped: remove ? 'not-reacted' : 'already-reacted' };
+        }
+        this.toggleReaction(chatId, targetGuid, true, undefined, undefined, 'custom', emoji);
+        return { ok: true };
+    }
+    // Targets an EXISTING chat only — no find-or-create `to:` form (contract §2).
+    async sendRich(chatId, text, opts = {}) {
+        await this.delay();
+        const chat = this.chats.get(chatId);
+        if (!chat)
+            return { ok: false };
+        // `effect` and `subject` have no fields in imsg's JSON message shape
+        // (docs/json.md) — they are write-only on the real path too, so the fake
+        // has nothing to store.
+        const msg = this.buildMessage(chat, { is_from_me: true, text, reply_to_guid: opts.replyToGuid });
+        this.emit(msg);
+        return { ok: true, id: msg.id, guid: msg.guid };
+    }
+    async sendAttachment(chatId, _filePath, opts = {}) {
+        await this.delay();
+        const chat = this.chats.get(chatId);
+        if (!chat)
+            return { ok: false };
+        // The send response does not carry attachment metadata. Do not invent
+        // readback fields before a later history/watch row supplies them.
+        const msg = this.buildMessage(chat, { is_from_me: true, reply_to_guid: opts.replyToGuid });
+        this.emit(msg);
+        return { ok: true, id: msg.id, guid: msg.guid };
+    }
+    async sendSticker(chatId, _filePath, _opts = {}) {
+        await this.delay();
+        if (!this.capabilities.stickerSend)
+            return { ok: false };
+        const chat = this.chats.get(chatId);
+        if (!chat)
+            return { ok: false };
+        // File validity and sticker rendering have no synchronous postcondition
+        // in the Gateway message shape; conservatively emit only the outbound row.
+        const msg = this.buildMessage(chat, { is_from_me: true });
+        this.emit(msg);
+        return { ok: true, id: msg.id, guid: msg.guid };
+    }
+    async sendPoll(chatId, question, options) {
+        await this.delay();
+        if (options.length < 2 || !this.chats.has(chatId))
+            return { ok: false };
+        const { balloon } = this.injectPollCreate({ chatId, fromMe: true, question, options });
+        return { ok: true, guid: balloon.guid };
+    }
+    async sendRichLink(chatId, _url) {
+        await this.delay();
+        const chat = this.chats.get(chatId);
+        if (!chat)
+            return { ok: false };
+        // The real send.rich url submode is queued and returns NO guid; the URL
+        // balloon lands as its own row later. Emit the row for stream parity but
+        // return only `{ ok }` — the fake must never hand back a guid the real
+        // path does not provide (rule 2). ImsgMessage has no rich-link field, so
+        // the preview itself is not observable through this interface either.
+        this.emit(this.buildMessage(chat, { is_from_me: true }));
+        return { ok: true };
+    }
+    // Edits mutate the target row's text IN PLACE — no new row, no subscribe()
+    // event (contract §2: this is what breaks the "same guid = immutable
+    // content" assumption elsewhere in the codebase).
+    async editMessage(chatId, targetGuid, text) {
+        await this.delay();
+        const target = this.findInScanWindow(chatId, targetGuid);
+        if (!target)
+            return { ok: false };
+        target.text = text;
+        return { ok: true };
+    }
+    // Live parity: unsend leaves a tombstone row whose text is cleared.
+    async unsendMessage(chatId, targetGuid) {
+        await this.delay();
+        const target = this.findInScanWindow(chatId, targetGuid);
+        if (!target)
+            return { ok: false };
+        target.text = undefined;
+        return { ok: true };
+    }
+    // Real deleteChatItems: has no stable history postcondition or deletion
+    // marker. Preserve the row here as the conservative no-queryable-mutation
+    // model so the fake never promises a readback capability the real path lacks.
+    async deleteMessage(chatId, targetGuid) {
+        await this.delay();
+        const target = this.findInScanWindow(chatId, targetGuid);
+        if (!target)
+            return { ok: false };
+        return { ok: true };
+    }
+    // Fire-and-forget: no observable effect through history() or this
+    // interface (contract §2) — the fake does not track a
+    // queryable typing/read state, matching real capability (parity rule 2).
+    async setTyping(chatId, _on) {
+        await this.delay();
+        return { ok: this.chats.has(chatId) };
+    }
+    async markRead(chatId) {
+        await this.delay();
+        return { ok: this.chats.has(chatId) };
+    }
+    async renameGroup(chatId, name) {
+        await this.delay();
+        const chat = this.chats.get(chatId);
+        if (!chat?.isGroup)
+            return { ok: false };
+        chat.name = name;
+        return { ok: true };
+    }
+    // No photo field exists anywhere in imsg's JSON output — fire-and-forget,
+    // same as setTyping/markRead (contract §2).
+    async setGroupPhoto(chatId, _filePath) {
+        await this.delay();
+        if (!this.capabilities.groupPhoto)
+            return { ok: false };
+        return { ok: Boolean(this.chats.get(chatId)?.isGroup) };
+    }
+    async addParticipant(chatId, handle) {
+        await this.delay();
+        if (!this.capabilities.groupParticipants)
+            return { ok: false };
+        const chat = this.chats.get(chatId);
+        if (!chat?.isGroup)
+            return { ok: false };
+        if (!chat.participants.includes(handle))
+            chat.participants.push(handle);
+        this.reachableAddresses.add(handle);
+        return { ok: true };
+    }
+    async removeParticipant(chatId, handle) {
+        await this.delay();
+        if (!this.capabilities.groupParticipants)
+            return { ok: false };
+        const chat = this.chats.get(chatId);
+        if (!chat?.isGroup)
+            return { ok: false };
+        chat.participants = chat.participants.filter((h) => h !== handle);
+        return { ok: true };
+    }
+    // participants[] excludes the local user always (contract §2 "Participants
+    // exclude the local user" — imsg docs/groups.md), so leaving never changes
+    // it — no observable field, fire-and-forget like setGroupPhoto.
+    async leaveGroup(chatId) {
+        await this.delay();
+        return { ok: Boolean(this.chats.get(chatId)?.isGroup) };
+    }
+    async shareNamePhoto(chatId) {
+        await this.delay();
+        if (!this.capabilities.namePhotoSharing || !this.chats.has(chatId))
+            return { ok: false, effectStarted: false };
+        if (this.namePhotoSharedChats.has(chatId))
+            return { ok: true, skipped: 'not-offered' };
+        this.namePhotoSharedChats.add(chatId);
+        return { ok: true };
+    }
+    // ---- fixture/test driver API (not part of Gateway) ----
+    // Reproduce the real gateway's bounded-directory failure. ImsgGateway sets
+    // directoryComplete=false when the chat scan hits GROUP_CHAT_SCAN_LIMIT or a
+    // group's history is unreadable; the fake has no scan limit, so without this
+    // it could never reach the state and rule 2's "never exceed the real
+    // gateway's capability" would be violated by omission.
+    setGroupDirectoryComplete(complete) {
+        this.groupDirectoryComplete = complete;
+    }
+    // Reproduce an imsg directory that reports a group without its `participants`
+    // list, which the wire type permits.
+    setGroupParticipantsUnreported(chatId, unreported) {
+        if (unreported)
+            this.groupParticipantsUnreported.add(chatId);
+        else
+            this.groupParticipantsUnreported.delete(chatId);
+    }
+    // Simulate an inbound text from another participant. Creates the DM chat
+    // if chatId is omitted (find-or-create by sender), or appends to an
+    // existing chat (DM or group) when chatId is given.
+    injectInbound(params) {
+        const chat = params.chatId !== undefined ? this.chats.get(params.chatId) : this.ensureDmChat(params.sender);
+        if (!chat)
+            throw new Error(`injectInbound: unknown chatId ${params.chatId}`);
+        const msg = this.buildMessage(chat, {
+            sender: params.sender,
+            sender_name: params.senderName,
+            is_from_me: false,
+            text: params.text,
+            attachments: params.attachments,
+        });
+        this.emit(msg);
+        return msg;
+    }
+    // Simulate another participant tapback-reacting (their side can target any
+    // message, same as real Messages.app — only OUR react() is most-recent-
+    // incoming-only).
+    injectReaction(params) {
+        if ((params.reaction === undefined) === (params.emoji === undefined)) {
+            throw new Error('injectReaction: provide exactly one of reaction or emoji');
+        }
+        const target = params.targetGuid ?? this.latestMessage(params.chatId)?.guid;
+        if (!target)
+            throw new Error('injectReaction: chat has no message to react to');
+        const type = params.reaction ?? 'custom';
+        const emoji = params.emoji ?? REACTION_EMOJI_BY_TYPE[params.reaction];
+        return this.toggleReaction(params.chatId, target, false, params.sender, params.senderName, type, emoji);
+    }
+    // ---- native poll fixtures (contract §2 "Native poll readback") ----
+    // Polls are created through sendPoll(), a manual host-Mac `imsg poll send`
+    // CLI op (fromMe: true here), or another participant's device. All three
+    // fixtures mirror the live wire shapes verified 2026-07-07 (docs/imsg-polls.md).
+    // A poll landing in a chat is TWO rows: the balloon row carrying the poll
+    // payload (display text "Sent a poll"), then a plain caption row with the
+    // question — Messages never renders the poll title on the balloon, so imsg
+    // always sends the caption.
+    injectPollCreate(params) {
+        if (params.options.length < 2)
+            throw new Error('injectPollCreate: pass at least two options');
+        const chat = params.chatId !== undefined
+            ? this.chats.get(params.chatId)
+            : params.sender !== undefined
+                ? this.ensureDmChat(params.sender)
+                : undefined;
+        if (!chat)
+            throw new Error(`injectPollCreate: unknown chatId ${params.chatId}`);
+        const fromMe = params.fromMe ?? false;
+        const balloon = this.buildMessage(chat, {
+            sender: fromMe ? undefined : params.sender,
+            sender_name: fromMe ? undefined : params.senderName,
+            is_from_me: fromMe,
+            text: 'Sent a poll',
+        });
+        balloon.poll = {
+            kind: 'created',
+            event: 'imessage.poll.created',
+            question: params.question,
+            options: params.options.map((text, i) => ({ id: `fake-opt-${balloon.id}-${i}`, text })),
+            creator: fromMe ? 'mapi' : params.sender,
+            poll_guid: balloon.guid,
+            metadata: { associated_message_type: 3 },
+        };
+        this.emit(balloon);
+        const caption = this.buildMessage(chat, {
+            sender: fromMe ? undefined : params.sender,
+            sender_name: fromMe ? undefined : params.senderName,
+            is_from_me: fromMe,
+            text: params.question,
+            reply_to_guid: balloon.guid,
+        });
+        this.emit(caption);
+        return { balloon, caption };
+    }
+    pollSnapshot(chatId, pollGuid) {
+        const snap = aggregatePolls(this.messages.filter((m) => m.chat_id === chatId)).find((p) => p.originGuid === pollGuid);
+        if (!snap)
+            throw new Error(`no poll with guid ${pollGuid} in chat ${chatId}`);
+        return snap;
+    }
+    // Simulate another participant voting. votes[] is that participant's
+    // CURRENT selections, not a delta — re-voting emits a new row carrying the
+    // new full selection. An empty selection is refused: bare vote retraction
+    // is unverified on the real path (docs/imsg-polls.md, open questions).
+    injectPollVote(params) {
+        if (!params.optionIds.length) {
+            throw new Error('injectPollVote: empty selection — vote retraction is unverified on the real path');
+        }
+        const chat = this.chats.get(params.chatId);
+        if (!chat)
+            throw new Error(`injectPollVote: unknown chatId ${params.chatId}`);
+        const snap = this.pollSnapshot(params.chatId, params.pollGuid);
+        const textById = new Map(snap.options.map((o) => [o.id, o.text]));
+        const votes = params.optionIds.map((optionId) => {
+            const optionText = textById.get(optionId);
+            if (optionText === undefined)
+                throw new Error(`injectPollVote: unknown option ${optionId}`);
+            return {
+                event_type: 'selected',
+                option_id: optionId,
+                option_text: optionText,
+                participant: params.sender,
+                server_time: `${Date.now() / 1000}`,
+            };
+        });
+        const msg = this.buildMessage(chat, {
+            sender: params.sender,
+            sender_name: params.senderName,
+            is_from_me: false,
+            // Live vote rows carry a single-space display text — the payload is
+            // the poll object.
+            text: ' ',
+            poll: {
+                kind: 'vote',
+                event: 'imessage.poll.voted',
+                vote: votes[0],
+                votes,
+                poll_guid: params.pollGuid,
+                original_guid: params.pollGuid,
+                metadata: { associated_message_type: 4000 },
+            },
+        });
+        this.emit(msg);
+        return msg;
+    }
+    // Simulate another participant using "Add Choice". Mirrors the live wire
+    // hazards on purpose: the row re-carries the FULL option list, is
+    // mislabeled kind:"created", and its question field is junk — consumers
+    // must classify via pollEventKind and join original_guid (src/polls.ts).
+    injectPollAddOption(params) {
+        const chat = this.chats.get(params.chatId);
+        if (!chat)
+            throw new Error(`injectPollAddOption: unknown chatId ${params.chatId}`);
+        const snap = this.pollSnapshot(params.chatId, params.pollGuid);
+        const msg = this.buildMessage(chat, {
+            sender: params.sender,
+            sender_name: params.senderName,
+            is_from_me: false,
+            // Live option-update rows display as U+FFFD.
+            text: '�',
+        });
+        msg.poll = {
+            kind: 'created',
+            event: 'imessage.poll.created',
+            question: '',
+            options: [...snap.options, { id: `fake-opt-${msg.id}`, text: params.optionText }],
+            creator: params.sender,
+            poll_guid: msg.guid,
+            original_guid: params.pollGuid,
+            metadata: { associated_message_type: 2 },
+        };
+        this.emit(msg);
+        return msg;
+    }
+    // Force the next send() to fail (contract §2 send-failure mode). Resets
+    // itself after firing once.
+    failNextSend() {
+        this.forcedSendFailure = true;
+    }
+    // Evidence override for handle-check tests/sim. Unknown well-formed
+    // addresses remain conservatively unavailable; this never queries Apple.
+    setHandleReachable(address, reachable) {
+        if (reachable)
+            this.reachableAddresses.add(address);
+        else
+            this.reachableAddresses.delete(address);
+    }
+    // Find-or-create the DM chat for a handle without sending anything — the
+    // simulator seeds empty DM panes with this before the first message.
+    ensureDm(handle) {
+        return this.ensureDmChat(handle).chatId;
+    }
+    // Read-only mirror of the whole store for the simulator UI. Deep-copied so
+    // callers can't mutate reaction aggregates behind the gateway's back.
+    snapshot() {
+        return {
+            chats: [...this.chats.values()].map((c) => ({
+                chatId: c.chatId,
+                chatGuid: c.guid,
+                isGroup: c.isGroup,
+                participants: [...c.participants],
+            })),
+            messages: structuredClone(this.messages),
+        };
+    }
+    // Hosted-Dev persistence only. This is not a Gateway capability: it restores
+    // a previously validated synthetic snapshot before the isolated world starts.
+    devRestoreSnapshot(input) {
+        const chats = new Map();
+        const messageIds = new Set();
+        for (const source of input.chats) {
+            if (!Number.isSafeInteger(source.chatId) || source.chatId < 1 || chats.has(source.chatId)) {
+                throw new Error('synthetic snapshot has an invalid chat identity');
+            }
+            const messageGuid = input.messages.find((message) => message.chat_id === source.chatId)?.chat_guid;
+            const guid = source.isGroup ? messageGuid : `any;-;${source.participants[0] ?? ''}`;
+            if (!guid || (source.isGroup ? !guid.startsWith('any;+;') : !guid.startsWith('any;-;'))) {
+                throw new Error('synthetic snapshot has no portable conversation identity');
+            }
+            chats.set(source.chatId, {
+                chatId: source.chatId,
+                guid,
+                isGroup: source.isGroup,
+                participants: [...source.participants],
+            });
+        }
+        const messages = input.messages.map((message) => structuredClone(message));
+        for (const message of messages) {
+            const chat = chats.get(message.chat_id);
+            if (!Number.isSafeInteger(message.id) ||
+                message.id < 1 ||
+                messageIds.has(message.id) ||
+                !chat ||
+                message.chat_guid !== chat.guid ||
+                message.is_group !== chat.isGroup) {
+                throw new Error('synthetic snapshot message conflicts with its chat');
+            }
+            messageIds.add(message.id);
+        }
+        this.chats = chats;
+        this.messages = messages;
+        this.nextChatId = Math.max(0, ...chats.keys()) + 1;
+        this.nextId = Math.max(0, ...messages.map((message) => message.id)) + 1;
+    }
+    // Tap every emitted event (messages AND reaction rows) without holding the
+    // single-consumer subscribe slot — the simulator uses this to know when to
+    // rebroadcast state. Returns an unsubscribe function.
+    onEvent(listener) {
+        this.subscribers.add(listener);
+        return () => {
+            this.subscribers.delete(listener);
+        };
+    }
+}
+//# sourceMappingURL=fake.js.map