@ouro.bot/cli 0.1.0-alpha.73 → 0.1.0-alpha.731

package/dist/mailroom/hosted-cache-sync.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mailSearchCacheDocumentMatchesRecord = mailSearchCacheDocumentMatchesRecord;
+exports.syncHostedMailSearchCache = syncHostedMailSearchCache;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const blob_store_1 = require("./blob-store");
+const core_1 = require("./core");
+const search_cache_1 = require("./search-cache");
+function filtersFor(input) {
+    return {
+        agentId: input.agentId,
+        ...(input.placement ? { placement: input.placement } : {}),
+        ...(input.scope ? { compartmentKind: input.scope } : {}),
+        ...(input.source ? { source: input.source } : {}),
+    };
+}
+function recordFor(message) {
+    return {
+        schemaVersion: 1,
+        id: message.id,
+        agentId: message.agentId,
+        compartmentKind: message.compartmentKind,
+        placement: message.placement,
+        ...(message.source ? { source: message.source } : {}),
+        receivedAt: message.receivedAt,
+    };
+}
+function sameOptionalText(left, right) {
+    return (left ?? "").toLowerCase() === (right ?? "").toLowerCase();
+}
+function mailSearchCacheDocumentMatchesRecord(document, record, requireKeyProvenance) {
+    return document.schemaVersion === 1
+        && document.agentId === record.agentId
+        && document.messageId === record.id
+        && document.receivedAt === record.receivedAt
+        && document.placement === record.placement
+        && document.compartmentKind === record.compartmentKind
+        && sameOptionalText(document.source, record.source)
+        && document.textProjectionVersion === search_cache_1.MAIL_SEARCH_TEXT_PROJECTION_VERSION
+        && (!requireKeyProvenance || typeof document.decryptionKeyId === "string");
+}
+function messageMatchesRecord(message, record) {
+    return message.id === record.id
+        && message.agentId === record.agentId
+        && message.receivedAt === record.receivedAt
+        && message.placement === record.placement
+        && message.compartmentKind === record.compartmentKind
+        && sameOptionalText(message.source, record.source);
+}
+async function scopedRecords(input) {
+    const filters = filtersFor(input);
+    const indexed = await input.store.listMessageIndexRecords?.(filters);
+    if (indexed)
+        return indexed;
+    return (await input.store.listMessages(filters)).map(recordFor);
+}
+async function fetchIndexedMessage(store, id) {
+    return store.getIndexedMessageById
+        ? store.getIndexedMessageById(id)
+        : store.getMessage(id);
+}
+function removeCanonicalIfPresent(agentId, messageId, options) {
+    return (0, search_cache_1.removeMailSearchCacheDocument)(agentId, messageId, options) ? 1 : 0;
+}
+function missingPrivateKeyId(error) {
+    if (!(error instanceof Error))
+        return null;
+    const keyId = error.keyId;
+    return typeof keyId === "string" && keyId.length > 0 ? keyId : null;
+}
+/**
+ * Converge a local decrypted cache against hosted index authority, or perform
+ * the legacy bounded upsert used by the in-agent refresh tool. This core never
+ * writes remote mail state and never records access; adapters own audit policy.
+ */
+async function performHostedMailSearchCacheSync(input) {
+    let authority = null;
+    let records;
+    if (input.mode === "full-convergence") {
+        const observer = input.authority ?? input.store;
+        if (!observer.observeMessageIndexAuthority) {
+            throw new Error("hosted mail authority observer is unavailable");
+        }
+        authority = await observer.observeMessageIndexAuthority(input.agentId);
+        if (authority.parseFailureCount > 0 || authority.duplicateIds.length > 0) {
+            throw new Error(`hosted mail authority is ambiguous: ${authority.parseFailureCount} malformed index name(s), ${authority.duplicateIds.length} duplicate message id(s)`);
+        }
+        if (authority.records.length === 0) {
+            throw new Error("hosted mail authority is empty and cannot safely drive full convergence");
+        }
+        records = authority.records;
+    }
+    else {
+        records = await scopedRecords(input);
+    }
+    const recordsById = new Map(records.map((record) => [record.id, record]));
+    const canonicalDocuments = new Map();
+    let removed = 0;
+    if (input.mode === "full-convergence") {
+        for (const inspected of (0, search_cache_1.inspectMailSearchCacheFiles)(input.agentId, input.cacheOptions)) {
+            const document = inspected.document;
+            const canonicalName = document ? `${document.messageId}.json` : null;
+            const record = document ? recordsById.get(document.messageId) : undefined;
+            if (!document || inspected.fileName !== canonicalName || document.agentId !== input.agentId || !record) {
+                removed += Number((0, search_cache_1.removeMailSearchCacheFile)(input.agentId, inspected.fileName, input.cacheOptions));
+                continue;
+            }
+            canonicalDocuments.set(document.messageId, document);
+        }
+    }
+    else {
+        for (const document of (0, search_cache_1.searchMailSearchCache)({
+            agentId: input.agentId,
+            placement: input.placement,
+            compartmentKind: input.scope,
+            source: input.source,
+        }, input.cacheOptions)) {
+            canonicalDocuments.set(document.messageId, document);
+        }
+    }
+    let fetched = 0;
+    let alreadyCached = 0;
+    let skipped = 0;
+    const failures = [];
+    for (const record of records) {
+        const cached = canonicalDocuments.get(record.id);
+        if (cached && input.mode === "full-convergence" && cached.decryptionKeyId && !input.privateKeys[cached.decryptionKeyId]) {
+            removed += removeCanonicalIfPresent(input.agentId, record.id, input.cacheOptions);
+            skipped += 1;
+            continue;
+        }
+        if (cached && mailSearchCacheDocumentMatchesRecord(cached, record, input.mode === "full-convergence")) {
+            alreadyCached += 1;
+            continue;
+        }
+        try {
+            const message = await fetchIndexedMessage(input.store, record.id);
+            if (!message)
+                throw new Error("indexed message was not retrievable");
+            fetched += 1;
+            if (!messageMatchesRecord(message, record)) {
+                throw new Error(`indexed message metadata did not match authority for ${record.id}`);
+            }
+            const decrypted = (0, core_1.readDecryptedMailMessage)(message, input.privateKeys);
+            (0, search_cache_1.upsertMailSearchCacheDocument)(message, decrypted.private, input.cacheOptions, {
+                ...(message.bodyForm === "encrypted" ? { decryptionKeyId: message.privateEnvelope.keyId } : {}),
+            });
+        }
+        catch (error) {
+            if (input.mode === "full-convergence" || missingPrivateKeyId(error)) {
+                removed += removeCanonicalIfPresent(input.agentId, record.id, input.cacheOptions);
+                skipped += 1;
+            }
+            else {
+                failures.push({ id: record.id, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    if (failures.length > 0) {
+        const sample = failures.slice(0, 3).map((entry) => `${entry.id}: ${entry.error}`).join("; ");
+        throw new Error(`mail search index refresh incomplete; ${failures.length} fetch failed. first failure(s): ${sample}`);
+    }
+    const cachedIds = new Set((0, search_cache_1.searchMailSearchCache)({
+        agentId: input.agentId,
+        placement: input.placement,
+        compartmentKind: input.scope,
+        source: input.source,
+    }, input.cacheOptions).filter((document) => recordsById.has(document.messageId)).map((document) => document.messageId));
+    const snapshot = authority?.snapshot ?? (0, blob_store_1.canonicalMailIndexRecordSnapshot)(records);
+    const coverage = (0, search_cache_1.writeMailSearchCoverageRecord)({
+        schemaVersion: 1,
+        agentId: input.agentId,
+        storeKind: input.storeKind,
+        ...(input.placement ? { placement: input.placement } : {}),
+        ...(input.scope ? { compartmentKind: input.scope } : {}),
+        ...(input.source ? { source: input.source } : {}),
+        indexedAt: new Date().toISOString(),
+        visibleMessageCount: records.length,
+        cachedMessageCount: cachedIds.size,
+        decryptableMessageCount: cachedIds.size,
+        skippedMessageCount: skipped,
+        messageIndexFingerprint: snapshot.messageIndexFingerprint,
+        textProjectionVersion: search_cache_1.MAIL_SEARCH_TEXT_PROJECTION_VERSION,
+        ...(snapshot.oldestReceivedAt ? { oldestReceivedAt: snapshot.oldestReceivedAt } : {}),
+        ...(snapshot.newestReceivedAt ? { newestReceivedAt: snapshot.newestReceivedAt } : {}),
+    }, input.cacheOptions);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_search_cache_synced",
+        message: "hosted mail search cache synchronized",
+        meta: {
+            agentId: input.agentId,
+            mode: input.mode,
+            visible: records.length,
+            fetched,
+            alreadyCached,
+            removed,
+            skipped,
+        },
+    });
+    return { coverage, fetched, alreadyCached, removed, skipped };
+}
+async function syncHostedMailSearchCache(input) {
+    const traceId = (0, node_crypto_1.randomUUID)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_search_cache_sync_start",
+        trace_id: traceId,
+        message: "synchronizing hosted mail search cache",
+        meta: { agentId: input.agentId, mode: input.mode, storeKind: input.storeKind },
+    });
+    try {
+        const result = await performHostedMailSearchCacheSync(input);
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_search_cache_sync_end",
+            trace_id: traceId,
+            message: "hosted mail search cache synchronization completed",
+            meta: {
+                agentId: input.agentId,
+                mode: input.mode,
+                storeKind: input.storeKind,
+                visible: result.coverage.visibleMessageCount,
+                fetched: result.fetched,
+                alreadyCached: result.alreadyCached,
+                removed: result.removed,
+                skipped: result.skipped,
+            },
+        });
+        return result;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_search_cache_sync_error",
+            trace_id: traceId,
+            level: "error",
+            message: "hosted mail search cache synchronization failed",
+            meta: {
+                agentId: input.agentId,
+                mode: input.mode,
+                storeKind: input.storeKind,
+                error: String(error),
+            },
+        });
+        throw error;
+    }
+}

package/dist/mailroom/mbox-import.js

@@ -0,0 +1,393 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitMboxMessages = splitMboxMessages;
+exports.importMboxToStore = importMboxToStore;
+exports.importMboxFileToStore = importMboxFileToStore;
+exports.cacheMatchingMailSearchDocumentsFromMboxFile = cacheMatchingMailSearchDocumentsFromMboxFile;
+const fs = __importStar(require("node:fs"));
+const runtime_1 = require("../nerves/runtime");
+const core_1 = require("./core");
+const search_cache_1 = require("./search-cache");
+const search_relevance_1 = require("./search-relevance");
+function splitMboxMessages(rawMbox) {
+    const text = rawMbox.toString("utf-8");
+    const separators = [...text.matchAll(/^From [^\r\n]*(?:\r?\n)/gm)];
+    if (separators.length === 0) {
+        const trimmed = text.trim();
+        return trimmed ? [Buffer.from(text, "utf-8")] : [];
+    }
+    const messages = separators
+        .map((match, index) => {
+        const start = match.index + match[0].length;
+        const end = index + 1 < separators.length ? separators[index + 1].index : text.length;
+        return text.slice(start, end).replace(/\r?\n$/, "");
+    })
+        .filter((message) => message.trim().length > 0)
+        .map((message) => Buffer.from(message, "utf-8"));
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_mbox_split",
+        message: "mbox payload split into messages",
+        meta: { messages: messages.length },
+    });
+    return messages;
+}
+function trimTrailingLineEnding(message) {
+    if (message.length >= 2 && message[message.length - 2] === 0x0d && message[message.length - 1] === 0x0a) {
+        return message.subarray(0, -2);
+    }
+    if (message.length >= 1 && message[message.length - 1] === 0x0a) {
+        return message.subarray(0, -1);
+    }
+    return message;
+}
+function isSeparatorLine(line) {
+    return line.length >= 5 &&
+        line[0] === 0x46 &&
+        line[1] === 0x72 &&
+        line[2] === 0x6f &&
+        line[3] === 0x6d &&
+        line[4] === 0x20;
+}
+async function* streamMboxMessagesFromFile(filePath) {
+    const stream = fs.createReadStream(filePath);
+    let pending = Buffer.alloc(0);
+    let currentParts = [];
+    const flushCurrent = () => {
+        if (currentParts.length === 0)
+            return null;
+        const message = trimTrailingLineEnding(Buffer.concat(currentParts));
+        currentParts = [];
+        return message;
+    };
+    for await (const chunk of stream) {
+        pending = pending.length > 0 ? Buffer.concat([pending, chunk]) : Buffer.from(chunk);
+        let newlineIndex = pending.indexOf(0x0a);
+        while (newlineIndex >= 0) {
+            const line = pending.subarray(0, newlineIndex + 1);
+            pending = pending.subarray(newlineIndex + 1);
+            if (isSeparatorLine(line)) {
+                const message = flushCurrent();
+                if (message && message.length > 0)
+                    yield message;
+            }
+            else {
+                currentParts.push(Buffer.from(line));
+            }
+            newlineIndex = pending.indexOf(0x0a);
+        }
+    }
+    if (pending.length > 0) {
+        if (isSeparatorLine(pending)) {
+            const message = flushCurrent();
+            if (message && message.length > 0)
+                yield message;
+        }
+        else {
+            currentParts.push(Buffer.from(pending));
+        }
+    }
+    const finalMessage = flushCurrent();
+    if (finalMessage && finalMessage.length > 0)
+        yield finalMessage;
+}
+function findSourceGrant(input) {
+    const ownerEmail = input.ownerEmail ? (0, core_1.normalizeMailAddress)(input.ownerEmail) : undefined;
+    const source = input.source?.trim().toLowerCase();
+    const grants = input.registry.sourceGrants.filter((grant) => {
+        if (!grant.enabled || grant.agentId !== input.agentId)
+            return false;
+        if (ownerEmail && (0, core_1.normalizeMailAddress)(grant.ownerEmail) !== ownerEmail)
+            return false;
+        if (source && grant.source.toLowerCase() !== source)
+            return false;
+        return true;
+    });
+    if (grants.length === 0) {
+        throw new Error(`No enabled Mailroom source grant found for ${input.agentId}${ownerEmail ? ` owner ${ownerEmail}` : ""}${source ? ` source ${source}` : ""}`);
+    }
+    if (grants.length > 1 && !ownerEmail && !source) {
+        throw new Error(`Multiple source grants found for ${input.agentId}; pass --owner-email or --source to choose one`);
+    }
+    return grants[0];
+}
+function parseMboxMessage(rawMessage, grant) {
+    const mailFrom = extractHeaderAddress(rawMessage, "from");
+    const messageDate = extractHeaderDate(rawMessage, "date");
+    return {
+        rawMessage,
+        envelope: {
+            mailFrom: mailFrom ? (0, core_1.normalizeMailAddress)(mailFrom) : "",
+            rcptTo: [(0, core_1.normalizeMailAddress)(grant.aliasAddress)],
+            remoteAddress: "mbox-import",
+        },
+        ...(messageDate ? { messageDate } : {}),
+    };
+}
+function latestMessageDate(messages) {
+    const timestamps = messages
+        .map((message) => message.messageDate?.getTime())
+        .filter((timestamp) => typeof timestamp === "number" && Number.isFinite(timestamp));
+    if (timestamps.length === 0)
+        return null;
+    return new Date(Math.max(...timestamps)).toISOString();
+}
+function readHeaderBlock(rawMessage) {
+    const crlfBoundary = rawMessage.indexOf("\r\n\r\n");
+    if (crlfBoundary >= 0) {
+        return rawMessage.subarray(0, crlfBoundary).toString("utf-8");
+    }
+    const lfBoundary = rawMessage.indexOf("\n\n");
+    if (lfBoundary >= 0) {
+        return rawMessage.subarray(0, lfBoundary).toString("utf-8");
+    }
+    return rawMessage.toString("utf-8");
+}
+function extractHeaderValue(rawMessage, headerName) {
+    const target = `${headerName.toLowerCase()}:`;
+    let currentHeader = "";
+    const unfoldedHeaders = [];
+    for (const line of readHeaderBlock(rawMessage).split(/\r?\n/)) {
+        if (/^[ \t]/.test(line) && currentHeader) {
+            currentHeader += ` ${line.trim()}`;
+            continue;
+        }
+        if (currentHeader)
+            unfoldedHeaders.push(currentHeader);
+        currentHeader = line;
+    }
+    if (currentHeader)
+        unfoldedHeaders.push(currentHeader);
+    const match = unfoldedHeaders.find((line) => line.toLowerCase().startsWith(target));
+    return match ? match.slice(target.length).trim() : "";
+}
+function extractHeaderAddress(rawMessage, headerName) {
+    const value = extractHeaderValue(rawMessage, headerName);
+    if (!value)
+        return "";
+    const bracketed = value.match(/<([^>]+)>/);
+    if (bracketed?.[1])
+        return bracketed[1];
+    const plain = value.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i);
+    return plain?.[0] ?? "";
+}
+function extractHeaderDate(rawMessage, headerName) {
+    const value = extractHeaderValue(rawMessage, headerName);
+    if (!value)
+        return undefined;
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed : undefined;
+}
+function normalizeSearchTerms(queryTerms) {
+    return queryTerms
+        .map((term) => term.trim().toLowerCase())
+        .filter((term) => term.length > 0);
+}
+function historicalImportClassification(resolvedPlacement, sourceGrant) {
+    return {
+        placement: resolvedPlacement,
+        candidate: false,
+        trustReason: `delegated source grant ${sourceGrant.source} historical mbox import`,
+    };
+}
+async function importParsedMessagesToStore(input) {
+    let imported = 0;
+    let duplicates = 0;
+    const messages = [];
+    let scanned = 0;
+    const importedAt = (input.importedAt ?? new Date()).toISOString();
+    const sourceFreshThrough = input.sourceFreshThrough ?? null;
+    const maxConcurrency = Math.max(1, input.maxConcurrency ?? 1);
+    const inFlight = new Set();
+    const enqueue = (parsedMessage) => {
+        const task = (async () => {
+            const result = await input.store.putRawMessage({
+                resolved: input.resolved,
+                envelope: parsedMessage.envelope,
+                rawMime: parsedMessage.rawMessage,
+                receivedAt: parsedMessage.messageDate ?? input.importedAt,
+                ingest: {
+                    schemaVersion: 1,
+                    kind: "mbox-import",
+                    importedAt,
+                    sourceFreshThrough,
+                    attentionSuppressed: true,
+                },
+                classification: historicalImportClassification(input.resolved.defaultPlacement, input.sourceGrant),
+            });
+            if (input.collectMessages !== false)
+                messages.push(result.message);
+            if (result.created)
+                imported += 1;
+            else
+                duplicates += 1;
+            input.onProgress?.({ scanned, imported, duplicates });
+        })().finally(() => {
+            inFlight.delete(task);
+        });
+        inFlight.add(task);
+        return task;
+    };
+    for await (const parsedMessage of input.parsedMessages) {
+        scanned += 1;
+        input.onProgress?.({ scanned, imported, duplicates });
+        enqueue(parsedMessage);
+        if (inFlight.size >= maxConcurrency) {
+            await Promise.race(inFlight);
+        }
+    }
+    await Promise.all(inFlight);
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_mbox_imported",
+        message: "mbox mail imported",
+        meta: { agentId: input.sourceGrant.agentId.toLowerCase(), scanned, imported, duplicates, grantId: input.sourceGrant.grantId },
+    });
+    return {
+        agentId: input.sourceGrant.agentId.toLowerCase(),
+        sourceGrant: input.sourceGrant,
+        scanned,
+        imported,
+        duplicates,
+        sourceFreshThrough,
+        messages,
+    };
+}
+async function scanMboxFileFreshness(filePath, sourceGrant) {
+    let latestTimestamp = Number.NEGATIVE_INFINITY;
+    for await (const rawMessage of streamMboxMessagesFromFile(filePath)) {
+        const parsedMessage = parseMboxMessage(rawMessage, sourceGrant);
+        if (parsedMessage.messageDate) {
+            latestTimestamp = Math.max(latestTimestamp, parsedMessage.messageDate.getTime());
+        }
+    }
+    return Number.isFinite(latestTimestamp) ? new Date(latestTimestamp).toISOString() : null;
+}
+function resolveImportTarget(input) {
+    const agentId = input.agentId.toLowerCase();
+    const sourceGrant = findSourceGrant({
+        registry: input.registry,
+        agentId,
+        ownerEmail: input.ownerEmail,
+        source: input.source,
+    });
+    const resolved = (0, core_1.resolveMailAddress)(input.registry, sourceGrant.aliasAddress);
+    /* v8 ignore start -- findSourceGrant and resolveMailAddress share the same registry; this is a corruption guard. @preserve */
+    if (!resolved) {
+        throw new Error(`Source grant alias ${sourceGrant.aliasAddress} is not resolvable`);
+    }
+    /* v8 ignore stop */
+    return { agentId, sourceGrant, resolved };
+}
+async function importMboxToStore(input) {
+    const target = resolveImportTarget(input);
+    const rawMessages = splitMboxMessages(input.rawMbox);
+    const parsedMessages = rawMessages.map((rawMessage) => parseMboxMessage(rawMessage, target.sourceGrant));
+    const sourceFreshThrough = latestMessageDate(parsedMessages);
+    return importParsedMessagesToStore({
+        sourceGrant: target.sourceGrant,
+        resolved: target.resolved,
+        store: input.store,
+        parsedMessages,
+        importedAt: input.importedAt,
+        collectMessages: true,
+        sourceFreshThrough,
+    });
+}
+async function importMboxFileToStore(input) {
+    const target = resolveImportTarget(input);
+    const sourceFreshThrough = await scanMboxFileFreshness(input.filePath, target.sourceGrant);
+    async function* parsedMessages() {
+        for await (const rawMessage of streamMboxMessagesFromFile(input.filePath)) {
+            yield parseMboxMessage(rawMessage, target.sourceGrant);
+        }
+    }
+    return importParsedMessagesToStore({
+        sourceGrant: target.sourceGrant,
+        resolved: target.resolved,
+        store: input.store,
+        parsedMessages: parsedMessages(),
+        importedAt: input.importedAt,
+        collectMessages: false,
+        sourceFreshThrough,
+        maxConcurrency: 8,
+        onProgress: input.onProgress,
+    });
+}
+async function cacheMatchingMailSearchDocumentsFromMboxFile(input) {
+    const target = resolveImportTarget(input);
+    const queryTerms = normalizeSearchTerms(input.queryTerms);
+    if (queryTerms.length === 0 || input.limit <= 0)
+        return [];
+    const matches = [];
+    for await (const rawMessage of streamMboxMessagesFromFile(input.filePath)) {
+        const parsedMessage = parseMboxMessage(rawMessage, target.sourceGrant);
+        const { privateEnvelope, metadata } = await (0, core_1.buildStoredMailMessageMetadata)({
+            resolved: target.resolved,
+            envelope: parsedMessage.envelope,
+            rawMime: parsedMessage.rawMessage,
+            receivedAt: parsedMessage.messageDate,
+            ingest: {
+                schemaVersion: 1,
+                kind: "mbox-import",
+                attentionSuppressed: true,
+            },
+            classification: historicalImportClassification(target.resolved.defaultPlacement, target.sourceGrant),
+        });
+        // Projection-only: we need a `StoredMailMessage` shape for buildMailSearchCacheDocument
+        // but never persist this view; the live import (via store.putRawMessage) is
+        // what writes the durable record.
+        const { rawObjectStem, ...rest } = metadata;
+        const message = {
+            ...rest,
+            rawObject: `${rawObjectStem}.eml`,
+            bodyForm: "plaintext",
+            private: privateEnvelope,
+        };
+        const document = (0, search_cache_1.buildMailSearchCacheDocument)(message, privateEnvelope);
+        if (!queryTerms.some((term) => document.searchText.includes(term)))
+            continue;
+        (0, search_cache_1.upsertMailSearchCacheDocument)(message, privateEnvelope);
+        matches.push(document);
+        matches.sort((left, right) => (0, search_relevance_1.compareByRelevanceThenRecency)({ document: left, relevance: (0, search_relevance_1.scoreMailSearchDocument)(left, queryTerms) }, { document: right, relevance: (0, search_relevance_1.scoreMailSearchDocument)(right, queryTerms) }));
+        if (matches.length > input.limit)
+            matches.length = input.limit;
+    }
+    return matches
+        .map((document) => ({ document, relevance: (0, search_relevance_1.scoreMailSearchDocument)(document, queryTerms) }))
+        .sort(search_relevance_1.compareByRelevanceThenRecency)
+        .map((entry) => entry.document);
+}