@hraness/ghostget 0.18.0 → 0.18.2

package/src/messaging-automation-validation.ts

@@ -0,0 +1,110 @@
+import { types } from "node:util";
+import type { AutomationAction, AutomationActionKind, AutomationCoordinate, AutomationIdentity, AutomationMessage } from "./messaging-automation-types";
+
+export const AUTOMATION_ACTION_KINDS = Object.freeze(["text", "attachment", "reaction", "sticker", "link", "poll", "app-clip", "experience"] as const);
+export function automationRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (types.isProxy(value) || typeof value !== "object" || value === null || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new Error("Messaging automation value must be a plain object.");
+  const fields = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(fields).length !== keys.length || keys.some(key => !Object.hasOwn(fields, key))
+    || Reflect.ownKeys(fields).some(key => typeof key !== "string" || !keys.includes(key) || !fields[key]?.enumerable || !("value" in fields[key]!))) {
+    throw new Error("Messaging automation value has unsupported fields.");
+  }
+  return value as Record<string, unknown>;
+}
+export function automationText(value: unknown, maximum = 256, empty = false): string {
+  if (typeof value !== "string" || (!empty && value.length === 0) || Buffer.byteLength(value) > maximum || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)
+    || Buffer.from(value, "utf8").toString("utf8") !== value) throw new Error("Messaging automation text is invalid or exceeds its bound.");
+  return value;
+}
+export function automationId(value: unknown): string {
+  const id = automationText(value, 256);
+  if (!/^[A-Za-z0-9._:-]+$/u.test(id)) throw new Error("Messaging automation identifier is invalid.");
+  return id;
+}
+export function automationDigest(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) throw new Error("Messaging automation digest is invalid.");
+  return value;
+}
+export function automationInteger(value: unknown, minimum: number, maximum: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new Error("Messaging automation integer is outside its bound.");
+  return value;
+}
+export function automationArray(value: unknown, maximum: number): readonly unknown[] {
+  if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > maximum
+    || Reflect.ownKeys(value).length !== value.length + 1) throw new Error("Messaging automation list is invalid or exceeds its bound.");
+  for (let i = 0; i < value.length; i++) {
+    const field = Object.getOwnPropertyDescriptor(value, String(i));
+    if (field === undefined || !field.enumerable || !("value" in field)) throw new Error("Messaging automation list must be dense data.");
+  }
+  return value;
+}
+export function automationDate(value: unknown): string {
+  const text = automationText(value, 32);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(text) || !Number.isFinite(Date.parse(text)) || new Date(text).toISOString() !== text) throw new Error("Messaging automation time must be canonical UTC.");
+  return text;
+}
+export function parseAutomationCoordinate(value: unknown): AutomationCoordinate {
+  if (typeof value !== "object" || value === null || types.isProxy(value)) throw new Error("Messaging coordinate is invalid.");
+  const provider = Object.getOwnPropertyDescriptor(value, "provider")?.value;
+  if (provider === "imessage") {
+    const r = automationRecord(value, ["provider", "chatGuid", "service", "observedChatRowId"]);
+    const chatGuid = automationText(r.chatGuid, 1024);
+    if (!chatGuid.startsWith("iMessage;") || r.service !== "iMessage") throw new Error("Only exact iMessage conversations are supported.");
+    return Object.freeze({ provider, chatGuid, service: "iMessage", observedChatRowId: automationInteger(r.observedChatRowId, 1, Number.MAX_SAFE_INTEGER) });
+  }
+  const r = automationRecord(value, ["provider", "conversationJid"]);
+  if (provider !== "whatsapp" || typeof r.conversationJid !== "string" || !/^(?:[1-9][0-9]{4,14}@s\.whatsapp\.net|[1-9][0-9]{4,19}@lid)$/u.test(r.conversationJid)) throw new Error("Only exact individual WhatsApp conversations are supported.");
+  return Object.freeze({ provider, conversationJid: r.conversationJid });
+}
+export function parseAutomationIdentity(value: unknown): AutomationIdentity {
+  const r = automationRecord(value, ["provider", "authId", "accountIdentity", "accountSubject", "implementationIdentity", "sourceGeneration"]);
+  if (r.provider !== "imessage" && r.provider !== "whatsapp") throw new Error("Messaging provider is invalid.");
+  return Object.freeze({ provider: r.provider, authId: automationId(r.authId), accountIdentity: automationDigest(r.accountIdentity), accountSubject: automationText(r.accountSubject, 512), implementationIdentity: automationDigest(r.implementationIdentity), sourceGeneration: automationText(r.sourceGeneration, 256) });
+}
+export function parseAutomationActionKind(value: unknown): AutomationActionKind {
+  if (!AUTOMATION_ACTION_KINDS.includes(value as AutomationActionKind)) throw new Error("Messaging action is unsupported.");
+  return value as AutomationActionKind;
+}
+function https(value: unknown): string {
+  const url = automationText(value, 4096);
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password) throw new Error("Messaging links require credential-free HTTPS.");
+  return url;
+}
+export function parseAutomationAction(value: unknown): AutomationAction {
+  if (typeof value !== "object" || value === null || types.isProxy(value)) throw new Error("Messaging action is invalid.");
+  const kind = parseAutomationActionKind(Object.getOwnPropertyDescriptor(value, "kind")?.value);
+  if (kind === "text") { const r = automationRecord(value, ["kind", "text"]); return Object.freeze({ kind, text: automationText(r.text, 65536) }); }
+  if (kind === "link" || kind === "app-clip") { const r = automationRecord(value, ["kind", "url"]); return Object.freeze({ kind, url: https(r.url) }); }
+  if (kind === "attachment") {
+    const r = automationRecord(value, ["kind", "assetId", "name", "mimeType"]);
+    const name = automationText(r.name, 255); const mimeType = automationText(r.mimeType, 128);
+    if (/[\\/\r\n]/u.test(name) || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/u.test(mimeType)) throw new Error("Messaging attachment metadata is invalid.");
+    return Object.freeze({ kind, assetId: automationId(r.assetId), name, mimeType });
+  }
+  if (kind === "reaction") {
+    const r = automationRecord(value, ["kind", "messageId", "emoji", "remove"]); const emoji = automationText(r.emoji, 64, true);
+    if (typeof r.remove !== "boolean" || (!r.remove && (emoji.length === 0 || [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(emoji)].length !== 1))) throw new Error("Messaging reaction is invalid.");
+    return Object.freeze({ kind, messageId: automationId(r.messageId), emoji, remove: r.remove });
+  }
+  if (kind === "sticker") { const r = automationRecord(value, ["kind", "assetId", "messageId"]); return Object.freeze({ kind, assetId: automationId(r.assetId), messageId: r.messageId === null ? null : automationId(r.messageId) }); }
+  if (kind === "poll") {
+    const r = automationRecord(value, ["kind", "question", "options", "maximumSelections"]);
+    const options = automationArray(r.options, 12).map(option => automationText(option, 256));
+    if (options.length < 2 || new Set(options).size !== options.length) throw new Error("Messaging poll needs distinct options.");
+    return Object.freeze({ kind, question: automationText(r.question, 1024), options: Object.freeze(options), maximumSelections: r.maximumSelections === null ? null : automationInteger(r.maximumSelections, 1, options.length) });
+  }
+  const r = automationRecord(value, ["kind", "experienceId", "parameters"]);
+  if (typeof r.parameters !== "object" || r.parameters === null || types.isProxy(r.parameters)) throw new Error("Messaging experience parameters are invalid.");
+  const keys = Object.keys(r.parameters); if (keys.length > 16) throw new Error("Messaging experience parameters exceed their bound.");
+  const parameters = automationRecord(r.parameters, keys);
+  return Object.freeze({ kind, experienceId: automationId(r.experienceId), parameters: Object.freeze(Object.fromEntries(keys.map(key => [automationId(key), automationText(parameters[key], 4096, true)]))) });
+}
+export function parseAutomationMessage(value: unknown): AutomationMessage {
+  const r = automationRecord(value, ["id", "coordinate", "direction", "occurredAt", "text", "kind", "relatedMessageId", "attachments"]);
+  if (r.direction !== "incoming" && r.direction !== "outgoing" && r.direction !== "unknown") throw new Error("Messaging authorship is invalid.");
+  if (r.kind !== "message" && r.kind !== "reaction" && r.kind !== "edit" && r.kind !== "delete") throw new Error("Messaging event kind is invalid.");
+  const attachments = automationArray(r.attachments, 20).map(value => { const a = automationRecord(value, ["name", "mimeType", "sizeBytes"]); return Object.freeze({ name: a.name === null ? null : automationText(a.name, 512), mimeType: a.mimeType === null ? null : automationText(a.mimeType, 256), sizeBytes: a.sizeBytes === null ? null : automationInteger(a.sizeBytes, 0, 1024 * 1024 * 1024) }); });
+  return Object.freeze({ id: automationId(r.id), coordinate: parseAutomationCoordinate(r.coordinate), direction: r.direction, occurredAt: automationDate(r.occurredAt), text: r.text === null ? null : automationText(r.text, 65536, true), kind: r.kind, relatedMessageId: r.relatedMessageId === null ? null : automationId(r.relatedMessageId), attachments: Object.freeze(attachments) });
+}

package/src/messaging-automation.ts

@@ -0,0 +1,356 @@
+import { Database, constants as sqlite } from "bun:sqlite";
+import { closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { canonicalJson, sha256 } from "./canonical-json";
+import { ensurePrivateStateDirectory, ghostgetStateHome, snapshotPrivateStateDirectory } from "./storage";
+import { AUTOMATION_ACTION_KINDS, automationArray, automationDate, automationDigest, automationId, automationInteger, automationRecord, automationText, parseAutomationAction, parseAutomationActionKind, parseAutomationCoordinate, parseAutomationIdentity, parseAutomationMessage } from "./messaging-automation-validation";
+import type { AutomationConversation, AutomationEnrollment, AutomationEvent, AutomationGrant, AutomationGrantRequest, AutomationIdentity, AutomationPlan, AutomationPlanRequest, AutomationProviderPage, AutomationProviderSendResult, AutomationRun, MessagingAutomationProvider } from "./messaging-automation-types";
+export * from "./messaging-automation-types";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+type StoredEnrollment = { id: string; data: string; cursor: string; revision: number; ready: number; baselining: number; gap: number; reason: string | null };
+type StoredGrant = { id: string; data: string; revoked: number; consumed: number; last_dispatch: number };
+type StoredRun = { id: string; plan_id: string; intent_id: string; enrollment_id: string; state: AutomationRun["state"]; accepted: string; total: number; reason: string | null };
+const RUN_COLUMNS = "id,plan_id,intent_id,enrollment_id,state,accepted,total,reason";
+const same = (a: unknown, b: unknown) => canonicalJson(a) === canonicalJson(b);
+const authority = (identity: AutomationIdentity, selected: AutomationConversation) => ({ identity, conversation: { ...selected, title: null } });
+const sameConversation = (a: AutomationConversation, b: AutomationConversation) => same({ ...a, title: null }, { ...b, title: null });
+const stopped = (signal?: AbortSignal) => { if (signal?.aborted) throw new Error("Messaging automation operation was cancelled."); };
+const CAPACITY = Object.freeze({ enrollments: 1000, grants: 10000, plans: 20000, runs: 20000, messages: 50000, events: 50000 });
+function grantData(value: unknown): AutomationGrantRequest {
+  const r = automationRecord(value, ["enrollmentId", "expectedBindingDigest", "actions", "expiresAt", "maximumActions", "minimumIntervalMs"]);
+  const actions = automationArray(r.actions, AUTOMATION_ACTION_KINDS.length).map(parseAutomationActionKind);
+  if (actions.length === 0 || new Set(actions).size !== actions.length) throw new Error("Messaging grant action list is invalid.");
+  return Object.freeze({ enrollmentId: automationId(r.enrollmentId), expectedBindingDigest: automationDigest(r.expectedBindingDigest), actions: Object.freeze(actions), expiresAt: automationDate(r.expiresAt), maximumActions: automationInteger(r.maximumActions, 1, 100000), minimumIntervalMs: automationInteger(r.minimumIntervalMs, 0, 86400000) });
+}
+function planData(value: unknown): AutomationPlan {
+  const r = automationRecord(value, ["enrollmentId", "expectedRevision", "intentId", "actions", "bindingDigest", "expiresAt", "id", "digest"]);
+  const actions = automationArray(r.actions, 8).map(parseAutomationAction);
+  if (actions.length === 0 || Buffer.byteLength(canonicalJson(actions)) > 256 * 1024) throw new Error("Messaging plan exceeds its bound.");
+  const binding = { enrollmentId: automationId(r.enrollmentId), expectedRevision: automationInteger(r.expectedRevision, 0, Number.MAX_SAFE_INTEGER), intentId: automationId(r.intentId), actions: Object.freeze(actions), bindingDigest: automationDigest(r.bindingDigest), expiresAt: automationDate(r.expiresAt) };
+  const digest = automationDigest(r.digest); const id = automationId(r.id);
+  if (sha256(canonicalJson(binding)) !== digest || id !== `plan:${digest}`) throw new Error("Messaging plan binding is invalid.");
+  return Object.freeze({ ...binding, id, digest });
+}
+
+function conversation(value: unknown): AutomationConversation {
+  const r = automationRecord(value, ["coordinate", "title", "kind", "participants"]);
+  const coordinate = parseAutomationCoordinate(r.coordinate);
+  const participants = automationArray(r.participants, 2).map(value => automationText(value, 512));
+  if (r.kind !== "single" || participants.length < 1 || new Set(participants).size !== participants.length) throw new Error("Messaging automation requires one verified individual conversation.");
+  return Object.freeze({ coordinate, title: r.title === null ? null : automationText(r.title, 512), kind: "single", participants: Object.freeze([...participants].sort()) });
+}
+function checkedPage(value: unknown, expected: AutomationIdentity, coordinate: AutomationConversation["coordinate"]): AutomationProviderPage {
+  const r = automationRecord(value, ["identity", "messages", "nextCursor", "caughtUp", "gap"]);
+  const identity = parseAutomationIdentity(r.identity);
+  if (!same(identity, expected) || typeof r.caughtUp !== "boolean" || typeof r.gap !== "boolean") throw new Error("Messaging provider identity or cursor state changed.");
+  const messages = automationArray(r.messages, 500).map(parseAutomationMessage);
+  if (messages.some(message => !same(message.coordinate, coordinate))) throw new Error("Messaging provider returned another conversation.");
+  return Object.freeze({ identity, messages: Object.freeze(messages), nextCursor: automationText(r.nextCursor, 4096), caughtUp: r.caughtUp, gap: r.gap });
+}
+function checkedResult(value: unknown): AutomationProviderSendResult {
+  if (typeof value !== "object" || value === null) throw new Error("Messaging provider result is invalid.");
+  const state = Object.getOwnPropertyDescriptor(value, "state")?.value;
+  if (state === "accepted") {
+    const r = automationRecord(value, ["state", "messageId", "providerReceiptId", "delivery"]);
+    if (r.delivery !== "unknown") throw new Error("Messaging provider delivery claim is unsupported.");
+    return { state, messageId: r.messageId === null ? null : automationId(r.messageId), providerReceiptId: r.providerReceiptId === null ? null : automationId(r.providerReceiptId), delivery: "unknown" };
+  }
+  const r = automationRecord(value, ["state", "reason"]);
+  if (state !== "not-started" && state !== "indeterminate") throw new Error("Messaging provider result is invalid.");
+  return { state, reason: automationText(r.reason, 1024) };
+}
+
+/**
+ * Durable host coordination, not a model runtime or a replacement permission policy.
+ * The owner invokes grant/revoke through Ghostget's private control boundary. A grant
+ * narrows an already permitted provider operation to one immutable conversation.
+ * Multiple processes are serialized at each durable claim; an unresolved run fences
+ * its enrollment across restarts. No startup path clears uncertain dispatch state.
+ */
+export class MessagingAutomationHost {
+  private readonly db: Database;
+  private readonly directory: string;
+  private readonly directoryIdentity: ReturnType<typeof ensurePrivateStateDirectory>;
+  private readonly fileIdentity: { dev: number; ino: number };
+  private readonly providers = new Map<string, MessagingAutomationProvider>();
+  private readonly cursorKey: Buffer;
+  private readonly controllers = new Set<AbortController>();
+  private readonly planControllers = new Map<string, Set<AbortController>>();
+  private readonly pending = new Set<Promise<unknown>>();
+  private closing = false;
+  private closed = false;
+  constructor(providers: readonly MessagingAutomationProvider[], private readonly environment: Environment = process.env, private readonly now: () => number = Date.now) {
+    if (providers.length > 16) throw new Error("Too many messaging providers.");
+    for (const provider of providers) {
+      if (this.providers.has(provider.provider)) throw new Error("Duplicate messaging provider.");
+      this.providers.set(provider.provider, provider);
+    }
+    this.directory = join(ghostgetStateHome(environment), "messaging", "automation");
+    this.directoryIdentity = ensurePrivateStateDirectory(this.directory, environment);
+    const path = join(this.directory, "host.sqlite");
+    const fd = openSync(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    try { const stat = fstatSync(fd); if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1) throw new Error("Unsafe messaging journal."); this.fileIdentity = { dev: stat.dev, ino: stat.ino }; } finally { closeSync(fd); }
+    this.checkFiles();
+    this.db = new Database(path, sqlite.SQLITE_OPEN_READWRITE | sqlite.SQLITE_OPEN_NOFOLLOW);
+    try {
+      this.db.exec("PRAGMA busy_timeout=250; PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA trusted_schema=OFF; PRAGMA secure_delete=ON; PRAGMA max_page_count=65536;");
+      const version = this.db.query<{ user_version: number }, []>("PRAGMA user_version").get()?.user_version;
+      if (version !== 0 && version !== 1 && version !== 2) throw new Error("Unsupported messaging journal schema.");
+      this.db.exec("CREATE TABLE IF NOT EXISTS metadata (key TEXT PRIMARY KEY,value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS enrollments (id TEXT PRIMARY KEY,data TEXT NOT NULL,cursor TEXT NOT NULL,revision INTEGER NOT NULL,ready INTEGER NOT NULL,reason TEXT); CREATE TABLE IF NOT EXISTS grants (id TEXT PRIMARY KEY,data TEXT NOT NULL,revoked INTEGER NOT NULL,consumed INTEGER NOT NULL,last_dispatch INTEGER NOT NULL); CREATE TABLE IF NOT EXISTS plans (id TEXT PRIMARY KEY,data TEXT NOT NULL); CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY,plan_id TEXT NOT NULL,intent_id TEXT NOT NULL UNIQUE,enrollment_id TEXT NOT NULL,state TEXT NOT NULL,accepted TEXT NOT NULL,total INTEGER NOT NULL,reason TEXT); CREATE INDEX IF NOT EXISTS runs_contact ON runs(enrollment_id,state); CREATE TABLE IF NOT EXISTS messages (enrollment_id TEXT NOT NULL,event_key TEXT NOT NULL,data TEXT NOT NULL,PRIMARY KEY(enrollment_id,event_key)); CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT,enrollment_id TEXT NOT NULL,revision INTEGER NOT NULL,data TEXT NOT NULL);");
+      // Upgrading an old cursor establishes a fresh live boundary. It must not
+      // turn its unconsumed historical backlog into new automatic replies.
+      if (version !== 2) this.db.transaction(() => {
+        this.db.exec("ALTER TABLE enrollments ADD COLUMN baselining INTEGER NOT NULL DEFAULT 1; ALTER TABLE enrollments ADD COLUMN gap INTEGER NOT NULL DEFAULT 0; UPDATE enrollments SET gap=CASE WHEN reason LIKE '%unresolved gap%' THEN 1 ELSE 0 END,ready=0; PRAGMA user_version=2;");
+      }).immediate();
+      else this.db.exec("PRAGMA user_version=2;");
+      this.db.exec("CREATE TABLE IF NOT EXISTS grant_intents (id TEXT PRIMARY KEY,request_digest TEXT NOT NULL,grant_id TEXT NOT NULL UNIQUE REFERENCES grants(id));");
+      this.db.query("INSERT OR IGNORE INTO metadata(key,value) VALUES('cursor-key',?)").run(randomBytes(32).toString("hex"));
+      this.cursorKey = Buffer.from(automationDigest(this.db.query<{ value: string }, []>("SELECT value FROM metadata WHERE key='cursor-key'").get()?.value), "hex");
+      this.checkFiles();
+    } catch (error) { this.db.close(); throw error; }
+  }
+  private checkFiles(): void {
+    snapshotPrivateStateDirectory(this.directory, this.environment, this.directoryIdentity);
+    for (const name of ["host.sqlite", "host.sqlite-journal", "host.sqlite-wal", "host.sqlite-shm"]) {
+      let stat: ReturnType<typeof lstatSync>; try { stat = lstatSync(join(this.directory, name)); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT" && name !== "host.sqlite") continue; throw error; }
+      if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || name.endsWith("-wal") || name.endsWith("-shm")
+        || (name === "host.sqlite" && (stat.dev !== this.fileIdentity.dev || stat.ino !== this.fileIdentity.ino))) throw new Error("Messaging journal filesystem identity changed.");
+    }
+  }
+  private ready(): void { if (this.closing || this.closed) throw new Error("Messaging automation host is closed."); this.checkFiles(); }
+  private capacity(table: keyof typeof CAPACITY, additional = 1): void {
+    const count = this.db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()!.n;
+    const pages = this.db.query<{ page_count: number }, []>("PRAGMA page_count").get()!.page_count;
+    const size = this.db.query<{ page_size: number }, []>("PRAGMA page_size").get()!.page_size;
+    // Keep substantial physical headroom for dispatch/result journals. Nothing
+    // evicts receipts or advances consumer cursors silently when the bound fills.
+    if (count + additional > CAPACITY[table] || pages * size >= 192 * 1024 * 1024) throw new Error("Messaging journal capacity reached; owner maintenance is required before further dispatch.");
+  }
+  private provider(id: string): MessagingAutomationProvider { const provider = this.providers.get(id); if (provider === undefined) throw new Error("Messaging provider is unavailable."); return provider; }
+  private row(id: string): StoredEnrollment { this.ready(); const row = this.db.query<StoredEnrollment, [string]>("SELECT * FROM enrollments WHERE id=?").get(automationId(id)); if (row === null) throw new Error("Messaging enrollment does not exist."); return row; }
+  private enrollment(row: StoredEnrollment): AutomationEnrollment {
+    const r = automationRecord(JSON.parse(row.data) as unknown, ["identity", "conversation", "bindingDigest"]);
+    const identity = parseAutomationIdentity(r.identity); const selected = conversation(r.conversation); const bindingDigest = automationDigest(r.bindingDigest);
+    if (sha256(canonicalJson(authority(identity, selected))) !== bindingDigest) throw new Error("Messaging enrollment binding is invalid.");
+    const ready = automationInteger(row.ready, 0, 1); const baselining = automationInteger(row.baselining, 0, 1); const gap = automationInteger(row.gap, 0, 1);
+    if (ready && (baselining || gap)) throw new Error("Messaging enrollment readiness is inconsistent.");
+    return Object.freeze({ id: automationId(row.id), identity, conversation: selected, bindingDigest, revision: automationInteger(row.revision, 0, Number.MAX_SAFE_INTEGER), ready: ready === 1, reason: row.reason === null ? null : automationText(row.reason, 1024) });
+  }
+  enrollments(): readonly AutomationEnrollment[] { this.ready(); return this.db.query<StoredEnrollment, []>("SELECT * FROM enrollments ORDER BY id LIMIT 1001").all().map(row => this.enrollment(row)); }
+  private async status(provider: MessagingAutomationProvider, signal?: AbortSignal) {
+    stopped(signal); const value = await provider.inspect(signal); stopped(signal);
+    const r = automationRecord(value, ["identity", "connected", "events", "actions"]); const identity = parseAutomationIdentity(r.identity);
+    if (identity.provider !== provider.provider || typeof r.connected !== "boolean") throw new Error("Messaging provider identity is invalid.");
+    const actions = automationRecord(r.actions, AUTOMATION_ACTION_KINDS);
+    for (const capability of [r.events, ...Object.values(actions)]) { const c = automationRecord(capability, ["available", "reason"]); if (typeof c.available !== "boolean") throw new Error("Messaging capability is invalid."); if (c.reason !== null) automationText(c.reason, 1024); }
+    return value;
+  }
+  async providerStatus(id: string, signal?: AbortSignal) {
+    this.ready(); return this.status(this.provider(automationId(id)), signal);
+  }
+  async conversations(raw: Readonly<{ provider: string; limit: number }>, signal?: AbortSignal) {
+    this.ready(); const r = automationRecord(raw, ["provider", "limit"]);
+    const provider = this.provider(automationId(r.provider)), limit = automationInteger(r.limit, 1, 200);
+    const status = await this.status(provider, signal);
+    const result = automationRecord(await provider.conversations({ limit }, signal), ["identity", "conversations", "complete"]); stopped(signal);
+    const identity = parseAutomationIdentity(result.identity);
+    if (!same(identity, status.identity) || typeof result.complete !== "boolean") throw new Error("Messaging discovery identity changed.");
+    const rows = automationArray(result.conversations, limit).filter(value => automationRecord(value, ["coordinate", "title", "kind", "participants"]).kind === "single").map(conversation);
+    if (rows.some(row => row.coordinate.provider !== identity.provider) || new Set(rows.map(row => canonicalJson(row.coordinate))).size !== rows.length) throw new Error("Messaging discovery contains conflicting conversations.");
+    return Object.freeze({ identity, conversations: Object.freeze(rows), complete: result.complete });
+  }
+  history(raw: Readonly<{ enrollmentId: string; limit: number }>) {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "limit"]), limit = automationInteger(r.limit, 1, 200);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId)));
+    const rows = this.db.query<{ data: string }, [string, number]>("SELECT data FROM messages WHERE rowid IN (SELECT MAX(rowid) FROM messages WHERE enrollment_id=? GROUP BY json_extract(data,'$.id')) ORDER BY json_extract(data,'$.occurredAt') DESC,rowid DESC LIMIT ?").all(enrollment.id, limit);
+    const messages = rows.map(row => parseAutomationMessage(JSON.parse(row.data) as unknown)).reverse();
+    if (messages.some(message => !same(message.coordinate, enrollment.conversation.coordinate))) throw new Error("Messaging stored history has another conversation.");
+    return Object.freeze({ enrollment, messages: Object.freeze(messages) });
+  }
+  async enroll(raw: Readonly<{ provider: string; coordinate: unknown }>, signal?: AbortSignal): Promise<AutomationEnrollment> {
+    this.ready(); const request = automationRecord(raw, ["provider", "coordinate"]); const coordinate = parseAutomationCoordinate(request.coordinate);
+    if (request.provider !== coordinate.provider) throw new Error("Messaging provider and coordinate disagree.");
+    const provider = this.provider(coordinate.provider); const status = await this.status(provider, signal);
+    const resolved = await provider.resolve(coordinate, signal); stopped(signal);
+    if (!same(parseAutomationIdentity(resolved.identity), status.identity)) throw new Error("Messaging identity changed during enrollment.");
+    const selected = conversation(resolved.conversation); if (!same(selected.coordinate, coordinate)) throw new Error("Messaging route resolution changed target.");
+    const history = checkedPage(await provider.history({ coordinate, limit: 200 }, signal), status.identity, coordinate); stopped(signal);
+    const binding = { identity: status.identity, conversation: selected }; const bindingDigest = sha256(canonicalJson(authority(status.identity, selected)));
+    const id = `enrollment:${randomUUID()}`;
+    this.ready(); this.db.transaction(() => {
+      this.capacity("enrollments"); this.capacity("messages", history.messages.length);
+      if (this.enrollments().some(enrollment => same(enrollment.identity, status.identity) && same(enrollment.conversation.coordinate, coordinate))) throw new Error("Conversation is already enrolled.");
+      this.db.query("INSERT INTO enrollments(id,data,cursor,revision,ready,reason,baselining,gap) VALUES(?,?,?,0,?,?,?,?)").run(id, canonicalJson({ ...binding, bindingDigest }), history.nextCursor, !history.gap && history.caughtUp ? 1 : 0, history.gap ? "Provider history has an unresolved gap." : history.caughtUp ? null : "Initial history catchup is incomplete.", history.caughtUp ? 0 : 1, history.gap ? 1 : 0);
+      for (const message of history.messages) this.db.query("INSERT OR IGNORE INTO messages VALUES(?,?,?)").run(id, sha256(canonicalJson(message)), canonicalJson(message));
+    }).immediate(); this.checkFiles();
+    return this.enrollment(this.row(id));
+  }
+  grant(raw: AutomationGrantRequest, intent?: string): AutomationGrant {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "expectedBindingDigest", "actions", "expiresAt", "maximumActions", "minimumIntervalMs"]);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId))); const expectedBindingDigest = automationDigest(r.expectedBindingDigest);
+    if (enrollment.bindingDigest !== expectedBindingDigest) throw new Error("Messaging enrollment changed before grant issuance.");
+    const actions = automationArray(r.actions, AUTOMATION_ACTION_KINDS.length).map(parseAutomationActionKind);
+    if (actions.length === 0 || new Set(actions).size !== actions.length) throw new Error("Messaging grant action list is invalid.");
+    const expiresAt = automationDate(r.expiresAt);
+    const grant = { enrollmentId: enrollment.id, expectedBindingDigest, actions: [...actions].sort(), expiresAt, maximumActions: automationInteger(r.maximumActions, 1, 100000), minimumIntervalMs: automationInteger(r.minimumIntervalMs, 0, 86400000) };
+    const intentId = intent === undefined ? null : automationId(intent), digest = sha256(canonicalJson(grant));
+    const result = this.db.transaction(() => {
+      if (intentId !== null) {
+        const previous = this.db.query<{ request_digest: string; grant_id: string }, [string]>("SELECT request_digest,grant_id FROM grant_intents WHERE id=?").get(intentId);
+        if (previous) {
+          if (automationDigest(previous.request_digest) !== digest) throw new Error("Messaging grant intent changed its request.");
+          return this.grantStatus(previous.grant_id);
+        }
+      }
+      if (Date.parse(expiresAt) <= this.now() || Date.parse(expiresAt) > this.now() + 30 * 86400000) throw new Error("Messaging grant must expire within 30 days.");
+      const id = `grant:${randomUUID()}`;
+      this.capacity("grants"); this.db.query("INSERT INTO grants VALUES(?,?,0,0,0)").run(id, canonicalJson(grant));
+      if (intentId !== null) this.db.query("INSERT INTO grant_intents VALUES(?,?,?)").run(intentId, digest, id);
+      return Object.freeze({ ...grant, id, revoked: false, consumedActions: 0 });
+    }).immediate(); this.checkFiles(); return result;
+  }
+  /** Resolves uncertain grant creation without issuing or renewing authority. */
+  grantByIntent(intentId: string): AutomationGrant | null {
+    this.ready(); const row = this.db.query<{ grant_id: string }, [string]>("SELECT grant_id FROM grant_intents WHERE id=?").get(automationId(intentId));
+    return row === null ? null : this.grantStatus(row.grant_id);
+  }
+  revoke(id: string): void { this.ready(); if (this.db.query("UPDATE grants SET revoked=1 WHERE id=?").run(automationId(id)).changes !== 1) throw new Error("Messaging grant does not exist."); this.checkFiles(); }
+  grantStatus(id: string): AutomationGrant {
+    this.ready(); const row = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(automationId(id));
+    if (row === null) throw new Error("Messaging grant does not exist.");
+    const grant = grantData(JSON.parse(row.data) as unknown);
+    return Object.freeze({ ...grant, id: automationId(row.id), revoked: automationInteger(row.revoked, 0, 1) === 1, consumedActions: automationInteger(row.consumed, 0, grant.maximumActions) });
+  }
+  private activeRun(enrollmentId: string): boolean { return this.db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM runs WHERE enrollment_id=? AND state IN ('started','partial','indeterminate')").get(enrollmentId)!.n > 0; }
+  async poll(enrollmentId: string, signal?: AbortSignal): Promise<AutomationEnrollment> {
+    const initial = this.row(enrollmentId); const enrollment = this.enrollment(initial);
+    if (this.activeRun(enrollmentId)) return enrollment;
+    const provider = this.provider(enrollment.identity.provider); const status = await this.status(provider, signal);
+    if (!same(status.identity, enrollment.identity)) { this.db.query("UPDATE enrollments SET ready=0,reason=? WHERE id=?").run("Provider identity changed; enroll the conversation again.", enrollmentId); throw new Error("Messaging provider identity changed."); }
+    if (!status.connected || !status.events.available) { this.db.query("UPDATE enrollments SET ready=0,reason=? WHERE id=?").run(status.events.reason ?? "Provider events are unavailable.", enrollmentId); return this.enrollment(this.row(enrollmentId)); }
+    const page = checkedPage(await provider.events({ coordinates: [enrollment.conversation.coordinate], cursor: initial.cursor, limit: 200 }, signal), enrollment.identity, enrollment.conversation.coordinate); stopped(signal);
+    this.ready(); this.db.transaction(() => {
+      const current = this.row(enrollmentId); if (current.cursor !== initial.cursor || current.revision !== initial.revision || current.baselining !== initial.baselining || current.gap !== initial.gap || this.activeRun(enrollmentId)) throw new Error("Messaging poll lost its concurrent cursor claim.");
+      this.capacity("messages", page.messages.length); if (!initial.baselining) this.capacity("events", page.messages.length);
+      let revision = initial.revision;
+      for (const [index, message] of page.messages.entries()) {
+        const data = canonicalJson(message);
+        const previous = this.db.query<{ data: string }, [string, string]>("SELECT data FROM messages WHERE enrollment_id=? AND json_extract(data,'$.id')=? ORDER BY rowid DESC LIMIT 1").get(enrollmentId, message.id);
+        if (previous?.data === data) continue;
+        // A→B→A is another change, not a lifetime duplicate. The provider cursor
+        // and page position identify this observation while latest state dedups
+        // overlap at page boundaries.
+        this.db.query("INSERT INTO messages VALUES(?,?,?)").run(enrollmentId, sha256(canonicalJson({ cursor: page.nextCursor, index, message })), data);
+        if (initial.baselining === 1) continue;
+        revision = automationInteger(revision + 1, 1, Number.MAX_SAFE_INTEGER);
+        this.db.query("INSERT INTO events(enrollment_id,revision,data) VALUES(?,?,?)").run(enrollmentId, revision, data);
+      }
+      const gap = initial.gap === 1 || page.gap;
+      this.db.query("UPDATE enrollments SET cursor=?,revision=?,ready=?,reason=?,baselining=?,gap=? WHERE id=?").run(page.nextCursor, revision, !gap && page.caughtUp ? 1 : 0, gap ? "Provider event stream has an unresolved gap." : page.caughtUp ? null : "Provider catchup is incomplete.", initial.baselining && !page.caughtUp ? 1 : 0, gap ? 1 : 0, enrollmentId);
+    }).immediate(); this.checkFiles(); return this.enrollment(this.row(enrollmentId));
+  }
+  events(raw: Readonly<{ enrollmentIds: readonly string[]; cursor: string | null; limit: number }>): Readonly<{ events: readonly AutomationEvent[]; nextCursor: string; caughtUp: boolean }> {
+    this.ready(); const r = automationRecord(raw, ["enrollmentIds", "cursor", "limit"]); const ids = automationArray(r.enrollmentIds, 100).map(automationId).sort();
+    if (ids.length === 0 || new Set(ids).size !== ids.length) throw new Error("Messaging event selection is invalid.");
+    for (const id of ids) this.row(id);
+    const limit = automationInteger(r.limit, 1, 500); const fingerprint = sha256(canonicalJson(ids)); let after = 0;
+    if (r.cursor !== null) {
+      const cursor = automationText(r.cursor, 4096); const [payload, signature, extra] = cursor.split(".");
+      if (payload === undefined || signature === undefined || extra !== undefined || !/^[a-f0-9]{64}$/u.test(signature)) throw new Error("Messaging cursor is invalid.");
+      const mac = createHmac("sha256", this.cursorKey).update(payload).digest(); if (!timingSafeEqual(Buffer.from(signature, "hex"), mac)) throw new Error("Messaging cursor is invalid.");
+      const decoded = automationRecord(JSON.parse(Buffer.from(payload, "base64url").toString()) as unknown, ["fingerprint", "after"]);
+      if (decoded.fingerprint !== fingerprint) throw new Error("Messaging cursor belongs to a different contact selection."); after = automationInteger(decoded.after, 0, Number.MAX_SAFE_INTEGER);
+    }
+    const rows = this.db.query<{ seq: number; enrollment_id: string; revision: number; data: string }, (string | number)[]>(`SELECT seq,enrollment_id,revision,data FROM events WHERE seq>? AND enrollment_id IN (${ids.map(() => "?").join(",")}) ORDER BY seq LIMIT ?`).all(after, ...ids, limit + 1);
+    const selected = rows.slice(0, limit); const payload = Buffer.from(canonicalJson({ fingerprint, after: selected.at(-1)?.seq ?? after })).toString("base64url");
+    return Object.freeze({ events: Object.freeze(selected.map(row => Object.freeze({ sequence: row.seq, enrollmentId: row.enrollment_id, revision: row.revision, message: parseAutomationMessage(JSON.parse(row.data) as unknown) }))), nextCursor: `${payload}.${createHmac("sha256", this.cursorKey).update(payload).digest("hex")}`, caughtUp: rows.length <= limit });
+  }
+  prepare(raw: AutomationPlanRequest): AutomationPlan {
+    this.ready(); const r = automationRecord(raw, ["enrollmentId", "expectedRevision", "intentId", "actions"]);
+    const enrollment = this.enrollment(this.row(automationId(r.enrollmentId))); const expectedRevision = automationInteger(r.expectedRevision, 0, Number.MAX_SAFE_INTEGER);
+    if (!enrollment.ready || enrollment.revision !== expectedRevision) throw new Error("Messaging context is stale or unavailable.");
+    const actions = automationArray(r.actions, 8).map(parseAutomationAction); if (actions.length === 0) throw new Error("Messaging plan is empty.");
+    if (Buffer.byteLength(canonicalJson(actions)) > 256 * 1024) throw new Error("Messaging plan exceeds its byte bound.");
+    const intentId = automationId(r.intentId); const binding = { enrollmentId: enrollment.id, expectedRevision, intentId, actions, bindingDigest: enrollment.bindingDigest, expiresAt: new Date(this.now() + 120000).toISOString() };
+    const digest = sha256(canonicalJson(binding)); const plan = Object.freeze({ ...binding, id: `plan:${digest}`, digest });
+    this.db.transaction(() => { this.capacity("plans"); this.db.query("INSERT OR IGNORE INTO plans VALUES(?,?)").run(plan.id, canonicalJson(plan)); }).immediate(); this.checkFiles(); return plan;
+  }
+  private runProjection(row: StoredRun): AutomationRun {
+    const accepted = automationArray(JSON.parse(row.accepted) as unknown, 8).map(value => { const r = automationRecord(value, ["messageId", "providerReceiptId"]); return Object.freeze({ messageId: r.messageId === null ? null : automationId(r.messageId), providerReceiptId: r.providerReceiptId === null ? null : automationId(r.providerReceiptId) }); });
+    const totalActions = automationInteger(row.total, 1, 8);
+    if (!["started", "accepted", "failed", "partial", "indeterminate"].includes(row.state) || accepted.length > totalActions || (row.state === "accepted" && accepted.length !== totalActions) || (row.state === "failed" && accepted.length !== 0)) throw new Error("Messaging run state is inconsistent.");
+    return Object.freeze({ id: automationId(row.id), planId: automationId(row.plan_id), intentId: automationId(row.intent_id), enrollmentId: automationId(row.enrollment_id), state: row.state, accepted: Object.freeze(accepted), totalActions, reason: row.reason === null ? null : automationText(row.reason, 1024), retryable: false });
+  }
+  run(id: string): AutomationRun { this.ready(); const row = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE id=?`).get(automationId(id)); if (row === null) throw new Error("Messaging run does not exist."); return this.runProjection(row); }
+  cancel(planId: string): boolean {
+    this.ready(); const controllers = this.planControllers.get(automationId(planId));
+    if (controllers === undefined) return false;
+    for (const controller of controllers) controller.abort(); return true;
+  }
+  submit(raw: Readonly<{ planId: string; grantId: string }>, signal?: AbortSignal): Promise<AutomationRun> {
+    this.ready(); const r = automationRecord(raw, ["planId", "grantId"]); const controller = new AbortController(); const abort = () => controller.abort(); signal?.addEventListener("abort", abort, { once: true }); if (signal?.aborted) controller.abort(); this.controllers.add(controller);
+    const planId = automationId(r.planId), grantId = automationId(r.grantId);
+    const owned = this.planControllers.get(planId) ?? new Set<AbortController>(); owned.add(controller); this.planControllers.set(planId, owned);
+    const operation = this.dispatch(planId, grantId, controller.signal);
+    this.pending.add(operation); void operation.finally(() => { signal?.removeEventListener("abort", abort); this.controllers.delete(controller); owned.delete(controller); if (!owned.size) this.planControllers.delete(planId); this.pending.delete(operation); }).catch(() => undefined); return operation;
+  }
+  private async dispatch(planId: string, grantId: string, signal: AbortSignal): Promise<AutomationRun> {
+    stopped(signal); const record = this.db.query<{ data: string }, [string]>("SELECT data FROM plans WHERE id=?").get(planId); if (record === null) throw new Error("Messaging plan does not exist.");
+    const plan = planData(JSON.parse(record.data) as unknown);
+    if (plan.id !== planId) throw new Error("Messaging plan binding is invalid.");
+    const existing = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE intent_id=?`).get(plan.intentId);
+    if (existing !== null) { if (existing.plan_id !== plan.id) throw new Error("Messaging intent already belongs to another plan."); return this.runProjection(existing); }
+    const enrollment = await this.poll(plan.enrollmentId, signal); const provider = this.provider(enrollment.identity.provider); const status = await this.status(provider, signal);
+    const route = await provider.resolve(enrollment.conversation.coordinate, signal); stopped(signal);
+    if (!same(parseAutomationIdentity(route.identity), enrollment.identity) || !sameConversation(conversation(route.conversation), enrollment.conversation) || !same(status.identity, enrollment.identity) || !status.connected) throw new Error("Messaging route or identity changed before dispatch.");
+    for (const action of plan.actions) if (!status.actions[parseAutomationAction(action).kind].available) throw new Error("Messaging action is unavailable for this provider.");
+    const runId = `run:${randomUUID()}`;
+    this.ready(); this.db.transaction(() => {
+      stopped(signal); const current = this.enrollment(this.row(plan.enrollmentId)); const now = this.now();
+      this.capacity("runs"); this.capacity("messages", 0); this.capacity("events", 0);
+      if (!current.ready || current.revision !== plan.expectedRevision || current.bindingDigest !== plan.bindingDigest || Date.parse(plan.expiresAt) <= now || this.activeRun(current.id)) throw new Error("Messaging context expired, changed, or has an unresolved run.");
+      const grantRow = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(grantId); if (grantRow === null) throw new Error("Messaging grant does not exist.");
+      const grant = grantData(JSON.parse(grantRow.data) as unknown);
+      automationInteger(grantRow.revoked, 0, 1); automationInteger(grantRow.consumed, 0, grant.maximumActions); automationInteger(grantRow.last_dispatch, 0, Number.MAX_SAFE_INTEGER);
+      if (grantRow.revoked !== 0 || grant.enrollmentId !== current.id || grant.expectedBindingDigest !== current.bindingDigest || Date.parse(grant.expiresAt) <= now
+        || grantRow.consumed + plan.actions.length > grant.maximumActions || (grantRow.last_dispatch !== 0 && now - grantRow.last_dispatch < grant.minimumIntervalMs)
+        || plan.actions.some(action => !grant.actions.includes(action.kind))) throw new Error("Messaging grant does not authorize this dispatch.");
+      this.db.query("INSERT INTO runs VALUES(?,?,?,?, 'started','[]',?,NULL)").run(runId, plan.id, plan.intentId, current.id, plan.actions.length);
+      this.db.query("UPDATE grants SET consumed=consumed+?,last_dispatch=? WHERE id=?").run(plan.actions.length, now, grantId);
+    }).immediate(); this.checkFiles();
+    const accepted: { messageId: string | null; providerReceiptId: string | null }[] = [];
+    let state: AutomationRun["state"] = "accepted"; let reason: string | null = null;
+    for (const [index, action] of plan.actions.entries()) {
+      try {
+        this.checkFiles();
+        const observed = checkedPage(await provider.events({ coordinates: [enrollment.conversation.coordinate], cursor: this.row(enrollment.id).cursor, limit: 200 }, signal), enrollment.identity, enrollment.conversation.coordinate);
+        const ownMessages = new Set(accepted.flatMap(receipt => receipt.messageId === null ? [] : [receipt.messageId]));
+        if (observed.gap || !observed.caughtUp || observed.messages.some(message => message.direction !== "outgoing" || message.kind !== "message" || !ownMessages.has(message.id))) {
+          state = accepted.length ? "partial" : "failed"; reason = "Conversation changed before the next action."; break;
+        }
+        const grantRow = this.db.query<StoredGrant, [string]>("SELECT * FROM grants WHERE id=?").get(grantId);
+        const grant = grantRow === null ? null : grantData(JSON.parse(grantRow.data) as unknown);
+        const current = this.enrollment(this.row(plan.enrollmentId));
+        if (signal.aborted || grantRow?.revoked !== 0 || grant === null || Date.parse(grant.expiresAt) <= this.now() || Date.parse(plan.expiresAt) <= this.now()
+          || grant.enrollmentId !== current.id || grant.expectedBindingDigest !== current.bindingDigest || current.bindingDigest !== plan.bindingDigest || !grant.actions.includes(action.kind)) {
+          state = accepted.length ? "partial" : "failed"; reason = "Dispatch permission expired or changed before the next action."; break;
+        }
+        const result = checkedResult(await provider.send({ identity: enrollment.identity, coordinate: enrollment.conversation.coordinate, action, intentId: `${plan.intentId}:${index}` }, signal));
+        if (result.state !== "accepted") { state = result.state === "indeterminate" ? "indeterminate" : accepted.length ? "partial" : "failed"; reason = result.reason; break; }
+        accepted.push({ messageId: result.messageId, providerReceiptId: result.providerReceiptId });
+        this.checkFiles(); if (this.db.query("UPDATE runs SET accepted=? WHERE id=? AND state='started'").run(canonicalJson(accepted), runId).changes !== 1) throw new Error("Messaging result journal lost its claim.");
+      } catch { state = "indeterminate"; reason = "Provider dispatch or result recording did not settle conclusively."; break; }
+    }
+    this.checkFiles(); if (this.db.query("UPDATE runs SET state=?,accepted=?,reason=? WHERE id=? AND state='started'").run(state, canonicalJson(accepted), reason, runId).changes !== 1) throw new Error("Messaging terminal result could not be recorded.");
+    const row = this.db.query<StoredRun, [string]>(`SELECT ${RUN_COLUMNS} FROM runs WHERE id=?`).get(runId)!; return this.runProjection(row);
+  }
+  async close(): Promise<void> {
+    if (this.closed) return; if (this.closing) throw new Error("Messaging automation shutdown is already in progress."); this.closing = true;
+    for (const controller of this.controllers) controller.abort();
+    const settled = await Promise.allSettled([...this.pending]); const providers = await Promise.allSettled([...this.providers.values()].map(provider => provider.close()));
+    this.db.close(); this.closed = true;
+    if (settled.some(result => result.status === "rejected") || providers.some(result => result.status === "rejected")) throw new Error("Messaging automation shutdown did not establish complete cleanup.");
+  }
+}

package/src/plugins/imessage-direct/plugin.ts

@@ -1,3 +1,4 @@
+import { automationOperationDefinitions } from "../../messaging-automation-descriptors";
 import {
   defineProviderPlugin,
   lazyLocalCliRuntime,
@@ -108,6 +109,12 @@ export const imessageDirectPlugin = defineProviderPlugin({
   sourceKind: "built-in",
   implementationSources: Object.freeze([
     ...providerImplementationEntry(import.meta.url),
+    Object.freeze({ label: "native/imsg-darwin-arm64.gz", url: new URL("../../assets/messaging-runtime/imsg-darwin-arm64.gz", import.meta.url) }),
+    Object.freeze({ label: "native/phone-number-metadata.json.gz", url: new URL("../../assets/messaging-runtime/phone-number-metadata.json.gz", import.meta.url) }),
+    Object.freeze({ label: "native/phone-number-privacy.plist.gz", url: new URL("../../assets/messaging-runtime/phone-number-privacy.plist.gz", import.meta.url) }),
+    Object.freeze({ label: "native/phone-number-info.plist.gz", url: new URL("../../assets/messaging-runtime/phone-number-info.plist.gz", import.meta.url) }),
+    Object.freeze({ label: "native/NOTICE.txt", url: new URL("../../assets/messaging-runtime/NOTICE.txt", import.meta.url) }),
+
     Object.freeze({
       label: "vendor/private-transport.patch",
       url: new URL(
@@ -122,6 +129,10 @@ export const imessageDirectPlugin = defineProviderPlugin({
         import.meta.url,
       ),
     }),
+    Object.freeze({
+      label: "vendor/no-fetch-rich-cards.patch",
+      url: new URL("./vendor/0003-feat-rpc-add-no-fetch-rich-cards.patch", import.meta.url),
+    }),
     Object.freeze({
       label: "vendor/provenance.json",
       url: new URL("./vendor/provenance.json", import.meta.url),
@@ -143,7 +154,7 @@ export const imessageDirectPlugin = defineProviderPlugin({
       sourceUrl: IMSG_TOOL_PIN.sourceUrl,
       artifacts: IMSG_TOOL_PIN.artifacts,
     },
-    operations,
+    operations: [...operations, ...automationOperationDefinitions("imessage")],
     subject: {
       format: "imessage:device-default:<sha256-messages-store-coordinate>",
       matches: (value) => /^imessage:device-default:[a-f0-9]{64}$/u.test(value),