@mapier/imsg-sdk 0.2.3 → 0.3.0

package/dist/gateway/chat-background.d.ts

@@ -0,0 +1,40 @@
+import type { ChatBackgroundStatusResponse } from '../imsg/rpc.js';
+import type { ChatBackgroundRemoveResult, ChatBackgroundSetResult, ChatBackgroundStatus } from './types.js';
+export declare const CHAT_BACKGROUND_SET_DEADLINE_MS = 90000;
+export declare const CHAT_BACKGROUND_REMOVE_DEADLINE_MS = 30000;
+export declare const CHAT_BACKGROUND_POLL_INTERVAL_MS = 1000;
+export declare const CHAT_BACKGROUND_HELPER_INTERVAL_MS = 15000;
+export declare const CHAT_BACKGROUND_HELPER_BACKOFF_CAP_MS = 60000;
+export declare function isBridgeTimeout(err: unknown): boolean;
+export declare function chatBackgroundEffectStarted(err: unknown): boolean;
+export declare function bridgeEffectStarted(err: unknown, provenRejections: readonly string[]): boolean;
+export declare function chatBackgroundEventBaseline(status: ChatBackgroundStatusResponse): number;
+export declare function didPersistRemove(current: ChatBackgroundStatusResponse, initialGuid: string | null, baseline: number): boolean;
+export declare function toChatBackgroundStatus(status: ChatBackgroundStatusResponse): ChatBackgroundStatus;
+export interface ChatBackgroundVerifyClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare const MONOTONIC_CLOCK: ChatBackgroundVerifyClock;
+export interface ChatBackgroundSetVerifyInput {
+    read(operationId?: string): Promise<ChatBackgroundStatusResponse>;
+    initialGuid: string | null;
+    operationId: string | undefined;
+    clock: ChatBackgroundVerifyClock;
+    log: (message: string) => void;
+    deadlineMs?: number;
+    intervalMs?: number;
+    helperIntervalMs?: number;
+    helperBackoffCapMs?: number;
+}
+export declare function verifyChatBackgroundSet(input: ChatBackgroundSetVerifyInput): Promise<ChatBackgroundSetResult>;
+export interface ChatBackgroundRemoveVerifyInput {
+    read(): Promise<ChatBackgroundStatusResponse>;
+    initial: ChatBackgroundStatusResponse;
+    accepted: ChatBackgroundStatusResponse;
+    clock: ChatBackgroundVerifyClock;
+    log: (message: string) => void;
+    deadlineMs?: number;
+    intervalMs?: number;
+}
+export declare function verifyChatBackgroundRemove(input: ChatBackgroundRemoveVerifyInput): Promise<ChatBackgroundRemoveResult>;

package/dist/gateway/chat-background.js

@@ -0,0 +1,219 @@
+// Chat-background verify-after-fire logic (Mapier-Labs/imsg#12), kept pure so
+// it is unit-testable with mocked reads and a virtual clock. ImsgGateway wires
+// it to the live `imsg rpc` child; nothing here touches a process.
+//
+// Native facts this encodes (imsg docs/chat-background.md,
+// ChatBackgroundMutation.swift, RPCServer+Support.swift):
+// - `chat.background.set`/`remove` return on helper acceptance; chat.db lags
+//   imagent, so persistence is proven by polling `chat.background.status`.
+// - A status read WITHOUT `operation_id` is a local chat.db read. WITH it the
+//   native handler also round-trips the helper over the bridge: a Messages
+//   main-thread hop that competes with the pipeline itself and, because the
+//   native JSON-RPC loop is strictly serial, holds every other gateway verb
+//   for up to 10 s on a stall. Helper reads are therefore rare and backed off.
+// - The helper record's `transfer_id` is what IMChat persists as the
+//   background guid. It is the ONLY evidence that correlates a chat.db guid
+//   with THIS operation; a lagging write from an earlier operation can satisfy
+//   every other signal (changed guid, newer set event).
+// - Every failure is JSON-RPC -32603 with the reason only in `error.data`.
+import { ImsgRpcError } from '../imsg/rpc.js';
+// The native CLI's own windows (90 polls / 30 polls at 1 s). Here they are
+// wall-clock deadlines, so a stalled bridge hop cannot stretch the wait.
+export const CHAT_BACKGROUND_SET_DEADLINE_MS = 90_000;
+export const CHAT_BACKGROUND_REMOVE_DEADLINE_MS = 30_000;
+export const CHAT_BACKGROUND_POLL_INTERVAL_MS = 1000;
+// Scheduled helper reads (early failure detection) at most this often; a
+// helper timeout doubles the gap up to the cap.
+export const CHAT_BACKGROUND_HELPER_INTERVAL_MS = 15_000;
+export const CHAT_BACKGROUND_HELPER_BACKOFF_CAP_MS = 60_000;
+// The helper's pre-queue refusals (IMsgChatBackground.m /
+// IMsgInjected.m handleRemoveChatBackground) plus the coordinator's own
+// "did not queue". Anything else under -32603 (bridge timeout, a dylib
+// exception raised after IMChat was invoked, ...) may have acted.
+const CHAT_BACKGROUND_PROVEN_REJECTIONS = [
+    'did not queue the chat background operation',
+    'Another chat background operation is already running',
+    'does not match expected GUID',
+    'Chat background selector unavailable',
+    'Chat background GUID selector unavailable',
+    'Chat background runtime unavailable',
+    'Chat is required',
+];
+// IMsgBridgeProtocol.swift `IMsgBridgeError.timeout`.
+const BRIDGE_TIMEOUT_DETAIL = 'Timed out waiting for response';
+export function isBridgeTimeout(err) {
+    return err instanceof ImsgRpcError && (err.data ?? '').includes(BRIDGE_TIMEOUT_DETAIL);
+}
+// Did the helper possibly act before the request failed? Proven "no": the
+// server rejected the params (-32602: unknown chat, bad preset) or the helper
+// refused before queueing (a known rejection reason in `data`). Everything
+// else — a bridge timeout, an exception after IMChat was invoked, a
+// non-structured rpc-child/transport failure — is ambiguous.
+export function chatBackgroundEffectStarted(err) {
+    return bridgeEffectStarted(err, CHAT_BACKGROUND_PROVEN_REJECTIONS);
+}
+// The same rule for any bridge verb whose server folds every failure into
+// -32603: `provenRejections` are the helper's pre-invoke refusal texts for
+// that verb (matched against `error.data`).
+export function bridgeEffectStarted(err, provenRejections) {
+    if (!(err instanceof ImsgRpcError))
+        return true;
+    if (err.code === -32602)
+        return false;
+    const detail = err.data ?? '';
+    return !provenRejections.some((reason) => detail.includes(reason));
+}
+// Highest known background-event ROWID before a mutation. Both the
+// date-ordered and the ROWID-ordered newest event feed in, so a row imagent
+// writes with an out-of-order date is still recognised as new.
+export function chatBackgroundEventBaseline(status) {
+    return Math.max(status.latest_event?.row_id ?? 0, status.newest_event?.row_id ?? 0);
+}
+function hasNewChatBackgroundEvent(status, action, baseline) {
+    for (const event of [status.latest_event, status.newest_event]) {
+        if (event && event.action === action && event.row_id > baseline)
+            return true;
+    }
+    return false;
+}
+// Native didPersistRemove: no guid, plus either a clear event past the
+// baseline, or — only when the pre-mutation snapshot recorded the background
+// that is now gone — an events table that is empty. An already-lagging empty
+// snapshot proves nothing: the clear event has to land first.
+export function didPersistRemove(current, initialGuid, baseline) {
+    if (current.background_channel_guid)
+        return false;
+    if (hasNewChatBackgroundEvent(current, 'clear', baseline))
+        return true;
+    return initialGuid !== null && !current.latest_event && !current.newest_event;
+}
+export function toChatBackgroundStatus(status) {
+    const guid = status.background_channel_guid;
+    return {
+        chatId: status.chat_id,
+        backgroundSet: status.background_set,
+        backgroundGuid: guid ? guid : null,
+    };
+}
+// The production clock. `performance.now()` is monotonic: a wall-clock
+// adjustment (NTP step, manual change) cannot move a deadline, whereas a
+// `Date.now()`-based deadline would stretch the wait by the size of a
+// backwards step — a 10-minute rollback turned a 90 s window into ~11 min.
+export const MONOTONIC_CLOCK = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+// Polls until chat.db shows a guid that the helper record correlates with
+// THIS operation, the helper reports failure, the record is gone, a
+// non-transient read error occurs, or the deadline passes. Only the
+// `transfer_id` match is success; every other exit is either a proven failure
+// with the effect started or ambiguity — never a guess.
+export async function verifyChatBackgroundSet(input) {
+    const { read, initialGuid, operationId, clock, log, deadlineMs = CHAT_BACKGROUND_SET_DEADLINE_MS, intervalMs = CHAT_BACKGROUND_POLL_INTERVAL_MS, helperIntervalMs = CHAT_BACKGROUND_HELPER_INTERVAL_MS, helperBackoffCapMs = CHAT_BACKGROUND_HELPER_BACKOFF_CAP_MS, } = input;
+    const startedAt = clock.now();
+    const deadline = startedAt + deadlineMs;
+    // A candidate is a chat.db guid that differs from the pre-mutation
+    // snapshot. Seeing a NEW one pulls the next helper read forward once
+    // (`pulled`), so it is confirmed at the next opportunity; after that only
+    // the scheduled cadence and the timeout backoff decide when the helper is
+    // read again. `rejected` is the last candidate the record disproved.
+    let pulled = null;
+    let rejected = null;
+    let helperGapMs = helperIntervalMs;
+    let nextHelperAt = startedAt + helperIntervalMs;
+    let loggedTimeout = false;
+    for (;;) {
+        const consultHelper = operationId !== undefined && clock.now() >= nextHelperAt;
+        let current;
+        try {
+            current = await read(consultHelper ? operationId : undefined);
+        }
+        catch (err) {
+            // A bridge hop timing out while the pipeline holds the main thread is
+            // not evidence either way: back the helper off and keep polling chat.db.
+            // Anything else (dead rpc child, transport loss) ends the wait.
+            if (!isBridgeTimeout(err)) {
+                log(`setChatBackground verification failed: ${String(err)}`);
+                return { ok: false, effectStarted: true };
+            }
+            if (!loggedTimeout) {
+                loggedTimeout = true;
+                log(`setChatBackground verification read timed out: ${String(err)}`);
+            }
+            if (consultHelper) {
+                helperGapMs = Math.min(helperGapMs * 2, helperBackoffCapMs);
+                nextHelperAt = clock.now() + helperGapMs;
+            }
+        }
+        if (current) {
+            if (consultHelper)
+                nextHelperAt = clock.now() + helperGapMs;
+            const guid = current.background_channel_guid;
+            const candidate = guid && guid !== initialGuid ? guid : null;
+            const operation = current.operation;
+            if (operation?.found) {
+                if (operation.state === 'failed') {
+                    log(`setChatBackground operation failed: ${operation.stage ?? 'unknown'}: ${operation.detail ?? 'unknown error'}`);
+                    return { ok: false, effectStarted: true };
+                }
+                if (candidate) {
+                    if (operation.transfer_id && candidate === operation.transfer_id) {
+                        return { ok: true, backgroundGuid: candidate, effectStarted: true };
+                    }
+                    // A different guid is a lagging write of another operation's
+                    // background, or the helper has not reached `invoked` yet and
+                    // nothing in chat.db can be ours. Wait for the guid to change.
+                    rejected = candidate;
+                }
+            }
+            else if (operation) {
+                // The helper no longer tracks the operation (bounded record table,
+                // Messages relaunch mid-flight). Nothing left can correlate a chat.db
+                // guid with THIS operation, so the outcome is unknowable from here.
+                log('setChatBackground operation record is gone; persistence cannot be correlated');
+                return { ok: false, effectStarted: true };
+            }
+            else if (candidate && candidate !== rejected && candidate !== pulled) {
+                pulled = candidate;
+                nextHelperAt = Math.min(nextHelperAt, clock.now() + intervalMs);
+            }
+        }
+        if (clock.now() + intervalMs >= deadline)
+            break;
+        await clock.sleep(intervalMs);
+    }
+    return { ok: false, effectStarted: true };
+}
+export async function verifyChatBackgroundRemove(input) {
+    const { read, initial, accepted, clock, log, deadlineMs = CHAT_BACKGROUND_REMOVE_DEADLINE_MS, intervalMs = CHAT_BACKGROUND_POLL_INTERVAL_MS, } = input;
+    const initialGuid = initial.background_channel_guid ?? null;
+    const baseline = chatBackgroundEventBaseline(initial);
+    if (didPersistRemove(accepted, initialGuid, baseline))
+        return { ok: true, effectStarted: true };
+    const deadline = clock.now() + deadlineMs;
+    let loggedTimeout = false;
+    for (;;) {
+        if (clock.now() + intervalMs > deadline)
+            break;
+        await clock.sleep(intervalMs);
+        let current;
+        try {
+            current = await read();
+        }
+        catch (err) {
+            if (!isBridgeTimeout(err)) {
+                log(`removeChatBackground verification failed: ${String(err)}`);
+                return { ok: false, effectStarted: true };
+            }
+            if (!loggedTimeout) {
+                loggedTimeout = true;
+                log(`removeChatBackground verification read timed out: ${String(err)}`);
+            }
+            continue;
+        }
+        if (didPersistRemove(current, initialGuid, baseline))
+            return { ok: true, effectStarted: true };
+    }
+    return { ok: false, effectStarted: true };
+}
+//# sourceMappingURL=chat-background.js.map

package/dist/gateway/chat-background.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-background.js","sourceRoot":"","sources":["../../src/gateway/chat-background.ts"],"names":[],"mappings":"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"}

package/dist/gateway/edit-message.d.ts

@@ -0,0 +1,17 @@
+import type { ImsgMessage } from '../types.js';
+import { type EditMessageResult, type GatewayCapabilities } from './types.js';
+export declare const EDIT_PREFLIGHT_LOCATE_ATTEMPTS = 3;
+export declare const EDIT_VERIFY_ATTEMPTS = 6;
+export declare const EDIT_POLL_INTERVAL_MS = 1000;
+export declare const EDIT_MESSAGE_PROVEN_REJECTIONS: readonly string[];
+export interface EditMessagePort {
+    capabilities: Pick<GatewayCapabilities, 'editMessage'>;
+    history(chatId: number): Promise<ImsgMessage[]>;
+    edit(chatId: number, targetGuid: string, text: string): Promise<{
+        ok: boolean;
+    }>;
+    sleep(ms: number): Promise<void>;
+    log(message: string): void;
+}
+export declare function awaitInHistory(port: Pick<EditMessagePort, 'history' | 'sleep'>, chatId: number, matches: (m: ImsgMessage) => boolean, attempts: number, delayFirst: boolean): Promise<ImsgMessage | undefined>;
+export declare function runEditMessage(port: EditMessagePort, chatId: number, targetGuid: string, text: string): Promise<EditMessageResult>;

package/dist/gateway/edit-message.js

@@ -0,0 +1,70 @@
+import { bridgeEffectStarted } from './chat-background.js';
+import { decideEditMessagePreflight } from './types.js';
+// How long a preflight waits for a just-sent guid to surface in history
+// before calling it absent: "a beat", not the full post-fire verify budget.
+export const EDIT_PREFLIGHT_LOCATE_ATTEMPTS = 3;
+// Post-fire read-back budget (the Tier-2 verify convention: 6 × 1 s).
+export const EDIT_VERIFY_ATTEMPTS = 6;
+export const EDIT_POLL_INTERVAL_MS = 1000;
+// handleEditMessage's pre-invoke refusals (IMsgInjected.m) — anything else
+// under -32603 (bridge timeout, an exception after IMChat was invoked) may
+// have edited the row.
+export const EDIT_MESSAGE_PROVEN_REJECTIONS = [
+    'Missing chatGuid',
+    'Missing messageGuid',
+    'Missing editedMessage',
+    'Chat not found:',
+    'No edit-message selector available',
+    'Message not found:',
+    'Message object not found:',
+    'Unexpected signature for',
+];
+// Poll history until a row matches, sleeping only BETWEEN attempts.
+// `delayFirst` is for post-fire verification, where the first read would
+// predate the effect; preflights read immediately.
+export async function awaitInHistory(port, chatId, matches, attempts, delayFirst) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (delayFirst || attempt > 0)
+            await port.sleep(EDIT_POLL_INTERVAL_MS);
+        const found = (await port.history(chatId)).find(matches);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+// Preflight (decideEditMessagePreflight, shared with FakeGateway) → fire →
+// verify by history read-back. Every exit is a proven refusal
+// (effectStarted:false), a confirmed edit, or an honest ambiguity
+// (effectStarted:true) — never a guess.
+export async function runEditMessage(port, chatId, targetGuid, text) {
+    if (!port.capabilities.editMessage || !text.trim())
+        return { ok: false, effectStarted: false };
+    let target;
+    try {
+        target = await awaitInHistory(port, chatId, (m) => m.guid === targetGuid, EDIT_PREFLIGHT_LOCATE_ATTEMPTS, false);
+    }
+    catch (err) {
+        port.log(`editMessage preflight failed: ${String(err)}`);
+        return { ok: false, effectStarted: false };
+    }
+    const decided = decideEditMessagePreflight(port.capabilities, target, text);
+    if (decided)
+        return decided;
+    try {
+        await port.edit(chatId, targetGuid, text);
+    }
+    catch (err) {
+        port.log(`editMessage failed: ${String(err)}`);
+        return { ok: false, effectStarted: bridgeEffectStarted(err, EDIT_MESSAGE_PROVEN_REJECTIONS) };
+    }
+    try {
+        const confirmed = await awaitInHistory(port, chatId, (m) => m.guid === targetGuid && m.text === text, EDIT_VERIFY_ATTEMPTS, true);
+        if (confirmed)
+            return { ok: true };
+    }
+    catch (err) {
+        port.log(`editMessage verification failed: ${String(err)}`);
+    }
+    return { ok: false, effectStarted: true };
+}
+//# sourceMappingURL=edit-message.js.map

package/dist/gateway/edit-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-message.js","sourceRoot":"","sources":["../../src/gateway/edit-message.ts"],"names":[],"mappings":"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"}

package/dist/gateway/external-ids.d.ts

@@ -1,3 +1,4 @@
+export declare function isBoundedId(value: string): boolean;
 export declare function isImessageParticipantExternalId(value: string): boolean;
 export declare function isImessageDmConversationExternalId(value: string): boolean;
 export declare function isImessageGroupConversationExternalId(value: string): boolean;

package/dist/gateway/external-ids.js

@@ -5,7 +5,9 @@
 // schemas wrap them.
 // Bounded-identifier envelope shared by every portable id: non-empty, capped,
 // no control characters, no surrounding whitespace.
-function isBoundedId(value) {
+// The envelope every iMessage identifier must satisfy before any format
+// check: non-empty, bounded, no surrounding whitespace, no control bytes.
+export function isBoundedId(value) {
     if (value.length < 1 || value.length > 512)
         return false;
     if (value.trim() !== value)

package/dist/gateway/external-ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"external-ids.js","sourceRoot":"","sources":["../../src/gateway/external-ids.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,qBAAqB;AAErB,8EAA8E;AAC9E,oDAAoD;AACpD,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IACzD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,KAAK,GAAG,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,kEAAkE;AAClE,2EAA2E;AAC3E,MAAM,UAAU,+BAA+B,CAAC,KAAa;IAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CACL,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC;QAClC,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,KAAK,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAChH,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,yBAAyB;AACzB,MAAM,UAAU,kCAAkC,CAAC,KAAa;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC;IACxB,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,+BAA+B,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACvH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,qCAAqC,CAAC,KAAa;IACjE,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"external-ids.js","sourceRoot":"","sources":["../../src/gateway/external-ids.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,qBAAqB;AAErB,8EAA8E;AAC9E,oDAAoD;AACpD,wEAAwE;AACxE,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IACzD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,KAAK,GAAG,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,kEAAkE;AAClE,2EAA2E;AAC3E,MAAM,UAAU,+BAA+B,CAAC,KAAa;IAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CACL,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC;QAClC,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,KAAK,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAChH,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,yBAAyB;AACzB,MAAM,UAAU,kCAAkC,CAAC,KAAa;IAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC;IACxB,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,+BAA+B,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACvH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,qCAAqC,CAAC,KAAa;IACjE,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/dist/gateway/fake.d.ts

@@ -1,5 +1,5 @@
 import type { MessageAttachment } from '../types.js';
-import type { Gateway, GatewayCapabilities, GatewayEvent, GatewayChat, GatewayHistoryRange, GroupChatResolution, GroupChatResolutionRequest, HandleCheck, ImsgMessage, NamePhotoShareResult, Reaction, ReactionNote, ReactResult, SendResult, SendStatus, SendTarget, TextFormatRange } from './types.js';
+import type { ChatBackgroundPreset, ChatBackgroundRemoveResult, ChatBackgroundSetResult, ChatBackgroundStatus, EditMessageResult, Gateway, GatewayCapabilities, GatewayEvent, GatewayChat, GatewayHistoryRange, GroupChatResolution, GroupChatResolutionRequest, HandleCheck, ImsgMessage, NamePhotoShareResult, Reaction, ReactionNote, ReactResult, SendResult, SendStatus, SendTarget, TextFormatRange } from './types.js';
 export interface FakeGatewayOptions {
     latencyMs?: number;
     capabilities?: Partial<GatewayCapabilities>;
@@ -20,6 +20,11 @@ export interface FakeGatewaySnapshotV1 {
         readonly namePhotoSharedChatIds: readonly number[];
         readonly groupDirectoryComplete: boolean;
         readonly groupParticipantsUnreportedChatIds: readonly number[];
+        readonly chatBackgrounds?: ReadonlyArray<{
+            readonly chatId: number;
+            readonly backgroundGuid: string;
+        }>;
+        readonly chatBackgroundSeq?: number;
     };
 }
 export type FakeGatewaySnapshot = FakeGatewaySnapshotV1;
@@ -30,6 +35,8 @@ export declare class FakeGateway implements Gateway {
     private groupDirectoryComplete;
     private groupParticipantsUnreported;
     private namePhotoSharedChats;
+    private chatBackgrounds;
+    private nextBackgroundSeq;
     private reachableAddresses;
     private sentGuids;
     private nextId;
@@ -84,9 +91,7 @@ export declare class FakeGateway implements Gateway {
     sendPoll(chatId: number, question: string, options: string[]): Promise<SendResult>;
     votePoll(chatId: number, pollGuid: string, optionId: string): Promise<ReactResult>;
     sendRichLink(chatId: number, _url: string): Promise<SendResult>;
-    editMessage(chatId: number, targetGuid: string, text: string): Promise<{
-        ok: boolean;
-    }>;
+    editMessage(chatId: number, targetGuid: string, text: string): Promise<EditMessageResult>;
     unsendMessage(chatId: number, targetGuid: string): Promise<{
         ok: boolean;
     }>;
@@ -115,6 +120,9 @@ export declare class FakeGateway implements Gateway {
         ok: boolean;
     }>;
     shareNamePhoto(chatId: number): Promise<NamePhotoShareResult>;
+    chatBackgroundStatus(chatId: number): Promise<ChatBackgroundStatus | null>;
+    setChatBackground(chatId: number, preset?: ChatBackgroundPreset): Promise<ChatBackgroundSetResult>;
+    removeChatBackground(chatId: number, expectedGuid?: string): Promise<ChatBackgroundRemoveResult>;
     setGroupDirectoryComplete(complete: boolean): void;
     setGroupParticipantsUnreported(chatId: number, unreported: boolean): void;
     injectInbound(params: {

package/dist/gateway/fake.js

@@ -1,9 +1,9 @@
 import { aggregatePolls } from '../polls.js';
-import { PATCHED_GATEWAY_CAPABILITIES, toReactionNoteType } from './types.js';
+import { CHAT_BACKGROUND_PRESETS, decideEditMessagePreflight, normalizeChatBackgroundGuard, PATCHED_GATEWAY_CAPABILITIES, sendRichPreflight, TIER2_HISTORY_SCAN_WINDOW, 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 HISTORY_SCAN_WINDOW = TIER2_HISTORY_SCAN_WINDOW;
 const REACTION_EMOJI_BY_TYPE = {
     love: '❤️',
     like: '👍',
@@ -37,6 +37,9 @@ function reactionEventText(type, emoji, isAdd, targetText) {
     // runtime.ts because is_reaction is handled first.
     return `Removed a ${type} from ${quotedTarget}`;
 }
+// Fake background GUIDs are minted from a per-gateway sequence so a re-set
+// always yields a NEW guid (the real path's persistence proof).
+const FAKE_BACKGROUND_GUID_PREFIX = 'fake-chat-background-';
 // 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.
@@ -49,6 +52,8 @@ export class FakeGateway {
     groupDirectoryComplete = true;
     groupParticipantsUnreported = new Set();
     namePhotoSharedChats = new Set();
+    chatBackgrounds = new Map();
+    nextBackgroundSeq = 1;
     reachableAddresses = new Set();
     sentGuids = new Set();
     nextId = 1;
@@ -468,9 +473,22 @@ export class FakeGateway {
         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.
+        // The real path's preflight (shared) plus the helper's membership rule:
+        // a mention must name a participant of the chat, matched exactly. A
+        // refused range sends nothing.
+        const preflight = sendRichPreflight(this.capabilities, text, opts.textFormatting);
+        if (preflight)
+            return preflight.result;
+        // The helper resolves the allowed set from the LIVE participant list and
+        // refuses every mention when that list is unreadable (empty set); the
+        // fake's unreported-directory state models exactly that.
+        const members = this.groupParticipantsUnreported.has(chatId) ? [] : chat.participants;
+        if (opts.textFormatting?.some((r) => r.mention !== undefined && !members.includes(r.mention))) {
+            return { ok: false, refused: 'mention-not-participant' };
+        }
+        // `effect`, `subject` and formatting 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 };
@@ -564,12 +582,18 @@ export class FakeGateway {
     // 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).
+    // The preflight is the real path's, verbatim (decideEditMessagePreflight):
+    // capability, non-blank text, scan window, own plain-text message only —
+    // so a retracted tombstone or an attachment row is refused here too — and
+    // unchanged text is an idempotent skip.
     async editMessage(chatId, targetGuid, text) {
         await this.delay();
         const target = this.findInScanWindow(chatId, targetGuid);
-        if (!target)
-            return { ok: false };
-        target.text = text;
+        const decided = decideEditMessagePreflight(this.capabilities, target, text);
+        if (decided)
+            return decided;
+        if (target)
+            target.text = text;
         return { ok: true };
     }
     // Live parity: unsend leaves a tombstone row whose text is cleared.
@@ -656,6 +680,41 @@ export class FakeGateway {
         this.namePhotoSharedChats.add(chatId);
         return { ok: true };
     }
+    // ---- Chat backgrounds (contract §2 "Chat backgrounds"). Backgrounds are
+    // chat-scoped state, not message rows: no subscribe() event, no history
+    // row — the real side records them in chat.db's background tables. ----
+    async chatBackgroundStatus(chatId) {
+        await this.delay();
+        if (!this.chats.has(chatId))
+            return null;
+        const backgroundGuid = this.chatBackgrounds.get(chatId) ?? null;
+        return { chatId, backgroundSet: backgroundGuid !== null, backgroundGuid };
+    }
+    async setChatBackground(chatId, preset = 'gradient') {
+        await this.delay();
+        if (!this.capabilities.chatBackgroundSet || !this.chats.has(chatId))
+            return { ok: false, effectStarted: false };
+        if (!CHAT_BACKGROUND_PRESETS.includes(preset))
+            return { ok: false, effectStarted: false };
+        const backgroundGuid = `${FAKE_BACKGROUND_GUID_PREFIX}${this.nextBackgroundSeq++}`;
+        this.chatBackgrounds.set(chatId, backgroundGuid);
+        return { ok: true, backgroundGuid, effectStarted: true };
+    }
+    async removeChatBackground(chatId, expectedGuid) {
+        await this.delay();
+        if (!this.capabilities.chatBackgroundRemove || !this.chats.has(chatId))
+            return { ok: false, effectStarted: false };
+        const current = this.chatBackgrounds.get(chatId);
+        // Same order as the helper: the guard is compared against the live guid
+        // (nothing live counts as a mismatch too) BEFORE the no-background no-op.
+        const guard = normalizeChatBackgroundGuard(expectedGuid);
+        if (guard !== undefined && guard !== current)
+            return { ok: false, effectStarted: false };
+        if (current === undefined)
+            return { ok: true, skipped: 'no-background' };
+        this.chatBackgrounds.delete(chatId);
+        return { ok: true, effectStarted: 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
@@ -866,6 +925,10 @@ export class FakeGateway {
                 namePhotoSharedChatIds: [...this.namePhotoSharedChats].sort((left, right) => left - right),
                 groupDirectoryComplete: this.groupDirectoryComplete,
                 groupParticipantsUnreportedChatIds: [...this.groupParticipantsUnreported].sort((left, right) => left - right),
+                chatBackgrounds: [...this.chatBackgrounds]
+                    .map(([chatId, backgroundGuid]) => ({ chatId, backgroundGuid }))
+                    .sort((left, right) => left.chatId - right.chatId),
+                chatBackgroundSeq: this.nextBackgroundSeq,
             },
         };
     }
@@ -912,10 +975,18 @@ export class FakeGateway {
         }
         const namePhotoSharedChats = new Set(input.gatewayState.namePhotoSharedChatIds);
         const groupParticipantsUnreported = new Set(input.gatewayState.groupParticipantsUnreportedChatIds);
+        const chatBackgroundEntries = input.gatewayState.chatBackgrounds ?? [];
+        const chatBackgrounds = new Map(chatBackgroundEntries.map((entry) => [entry.chatId, entry.backgroundGuid]));
+        const nextBackgroundSeq = input.gatewayState.chatBackgroundSeq ?? 1;
         if (namePhotoSharedChats.size !== input.gatewayState.namePhotoSharedChatIds.length ||
             [...namePhotoSharedChats].some((chatId) => !chats.has(chatId)) ||
             groupParticipantsUnreported.size !== input.gatewayState.groupParticipantsUnreportedChatIds.length ||
-            [...groupParticipantsUnreported].some((chatId) => !chats.get(chatId)?.isGroup)) {
+            [...groupParticipantsUnreported].some((chatId) => !chats.get(chatId)?.isGroup) ||
+            chatBackgrounds.size !== chatBackgroundEntries.length ||
+            [...chatBackgrounds.keys()].some((chatId) => !chats.has(chatId)) ||
+            [...chatBackgrounds.values()].some((guid) => !guid) ||
+            !Number.isSafeInteger(nextBackgroundSeq) ||
+            nextBackgroundSeq < 1) {
             throw new Error('synthetic snapshot has invalid chat-scoped gateway state');
         }
         this.chats = chats;
@@ -923,6 +994,8 @@ export class FakeGateway {
         this.sentGuids = sentGuids;
         this.reachableAddresses = new Set(input.gatewayState.reachableAddresses);
         this.namePhotoSharedChats = namePhotoSharedChats;
+        this.chatBackgrounds = chatBackgrounds;
+        this.nextBackgroundSeq = nextBackgroundSeq;
         this.groupDirectoryComplete = input.gatewayState.groupDirectoryComplete;
         this.groupParticipantsUnreported = groupParticipantsUnreported;
         this.nextChatId = Math.max(0, ...chats.keys()) + 1;